6/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and/or distribute this software for any
   9  - purpose with or without fee is hereby granted, provided that the above
  10  - copyright notice and this permission notice appear in all copies.
  11  -
  12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18  - PERFORMANCE OF THIS SOFTWARE.
  19 -->
  20
  21 <!-- $Id: lwres_getrrsetbyname.docbook,v 1.3.206.6 2007/08/28 07:19:18 tbox Exp $ -->
  22
  23 <refentry>
  24 <refentryinfo>
  25
  26
  27 <date>Oct 18, 2000</date>
  28 </refentryinfo>
  29 <refmeta>
  30 <refentrytitle>lwres_getrrsetbyname</refentrytitle>
  31 <manvolnum>3</manvolnum>
  32 <refmiscinfo>BIND9</refmiscinfo>
  33 </refmeta>
  34
  35   <docinfo>
  36     <copyright>
  37       <year>2004</year>
  38       <year>2005</year>
  39       <year>2007</year>
  40       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  41     </copyright>
  42     <copyright>
  43       <year>2000</year>
  44       <year>2001</year>
  45       <holder>Internet Software Consortium.</holder>
  46     </copyright>
  47   </docinfo>
  48
  49 <refnamediv>
  50 <refname>lwres_getrrsetbyname</refname>
  51 <refname>lwres_freerrset</refname>
  52 <refpurpose>retrieve DNS records</refpurpose>
  53 </refnamediv>
  54 <refsynopsisdiv>
  55 <funcsynopsis>
  56 <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
  57 <funcprototype>
  58 <funcdef>
  59 int
  60 <function>lwres_getrrsetbyname</function></funcdef>
  61 <paramdef>const char *hostname</paramdef>
  62 <paramdef>unsigned int rdclass</paramdef>
  63 <paramdef>unsigned int rdtype</paramdef>
  64 <paramdef>unsigned int flags</paramdef>
  65 <paramdef>struct rrsetinfo **res</paramdef>
  66 </funcprototype>
  67 <funcprototype>
  68 <funcdef>
  69 void
  70 <function>lwres_freerrset</function></funcdef>
  71 <paramdef>struct rrsetinfo *rrset</paramdef>
  72 </funcprototype>
  73 </funcsynopsis>
  74
  75 <para>
  76 The following structures are used:
  77 <programlisting>
  78 struct  rdatainfo {
  79         unsigned int            rdi_length;     /* length of data */
  80         unsigned char           *rdi_data;      /* record data */
  81 };
  82
  83 struct  rrsetinfo {
  84         unsigned int            rri_flags;      /* RRSET_VALIDATED... */
  85         unsigned int            rri_rdclass;    /* class number */
  86         unsigned int            rri_rdtype;     /* RR type number */
  87         unsigned int            rri_ttl;        /* time to live */
  88         unsigned int            rri_nrdatas;    /* size of rdatas array */
  89         unsigned int            rri_nsigs;      /* size of sigs array */
  90         char                    *rri_name;      /* canonical name */
  91         struct rdatainfo        *rri_rdatas;    /* individual records */
  92         struct rdatainfo        *rri_sigs;      /* individual signatures */
  93 };
  94 </programlisting>
  95 </para>
  96 </refsynopsisdiv>
  97
  98 <refsect1>
  99 <title>DESCRIPTION</title>
 100 <para>
 101 <function>lwres_getrrsetbyname()</function>
 102 gets a set of resource records associated with a
 103 <parameter>hostname</parameter>,
 104
 105 <parameter>class</parameter>,
 106
 107 and
 108 <parameter>type</parameter>.
 109
 110 <parameter>hostname</parameter>
 111 is
 112 a pointer a to null-terminated string.  The
 113 <parameter>flags</parameter>
 114 field is currently unused and must be zero.
 115 </para>
 116 <para>
 117 After a successful call to
 118 <function>lwres_getrrsetbyname()</function>,
 119
 120 <parameter>*res</parameter>
 121 is a pointer to an
 122 <type>rrsetinfo</type>
 123 structure, containing a list of one or more
 124 <type>rdatainfo</type>
 125 structures containing resource records and potentially another list of
 126 <type>rdatainfo</type>
 127 structures containing SIG resource records
 128 associated with those records.
 129 The members
 130 <constant>rri_rdclass</constant>
 131 and
 132 <constant>rri_rdtype</constant>
 133 are copied from the parameters.
 134 <constant>rri_ttl</constant>
 135 and
 136 <constant>rri_name</constant>
 137 are properties of the obtained rrset.
 138 The resource records contained in
 139 <constant>rri_rdatas</constant>
 140 and
 141 <constant>rri_sigs</constant>
 142 are in uncompressed DNS wire format.
 143 Properties of the rdataset are represented in the
 144 <constant>rri_flags</constant>
 145 bitfield.  If the RRSET_VALIDATED bit is set, the data has been DNSSEC
 146 validated and the signatures verified.
 147 </para>
 148 <para>
 149 All of the information returned by
 150 <function>lwres_getrrsetbyname()</function>
 151 is dynamically allocated: the
 152 <constant>rrsetinfo</constant>
 153 and
 154 <constant>rdatainfo</constant>
 155 structures,
 156 and the canonical host name strings pointed to by the
 157 <constant>rrsetinfo</constant>structure.
 158
 159 Memory allocated for the dynamically allocated structures created by
 160 a successful call to
 161 <function>lwres_getrrsetbyname()</function>
 162 is released by
 163 <function>lwres_freerrset()</function>.
 164
 165 <parameter>rrset</parameter>
 166 is a pointer to a
 167 <type>struct rrset</type>
 168 created by a call to
 169 <function>lwres_getrrsetbyname()</function>.
 170
 171 </para>
 172 <para>
 173 </para>
 174 </refsect1>
 175 <refsect1>
 176 <title>RETURN VALUES</title>
 177 <para>
 178 <function>lwres_getrrsetbyname()</function>
 179 returns zero on success, and one of the following error
 180 codes if an error occurred:
 181 <variablelist>
 182
 183 <varlistentry><term><constant>ERRSET_NONAME</constant></term>
 184 <listitem><para>
 185 the name does not exist
 186 </para></listitem></varlistentry>
 187
 188 <varlistentry><term><constant>ERRSET_NODATA</constant></term>
 189 <listitem><para>
 190 the name exists, but does not have data of the desired type
 191 </para></listitem></varlistentry>
 192
 193 <varlistentry><term><constant>ERRSET_NOMEMORY</constant></term>
 194 <listitem><para>
 195 memory could not be allocated
 196 </para></listitem></varlistentry>
 197
 198 <varlistentry><term><constant>ERRSET_INVAL</constant></term>
 199 <listitem><para>
 200 a parameter is invalid
 201 </para></listitem></varlistentry>
 202
 203 <varlistentry><term><constant>ERRSET_FAIL</constant></term>
 204 <listitem><para>
 205 other failure
 206 </para></listitem></varlistentry>
 207
 208 <varlistentry><term><constant></constant></term>
 209 <listitem><para>
 210 </para></listitem></varlistentry>
 211
 212 </variablelist>
 213
 214 </para>
 215 </refsect1>
 216 <refsect1>
 217 <title>SEE ALSO</title>
 218 <para>
 219 <citerefentry>
 220 <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 221 </citerefentry>.
 222 </para>
 223
 224 </refsect1>
 225 </refentry>