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.10 2007/06/18 23:47:51 tbox Exp $ -->
  22 <refentry>
  23
  24   <refentryinfo>
  25     <date>Oct 18, 2000</date>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>lwres_getrrsetbyname</refentrytitle>
  30     <manvolnum>3</manvolnum>
  31     <refmiscinfo>BIND9</refmiscinfo>
  32   </refmeta>
  33
  34   <docinfo>
  35     <copyright>
  36       <year>2004</year>
  37       <year>2005</year>
  38       <year>2007</year>
  39       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  40     </copyright>
  41     <copyright>
  42       <year>2000</year>
  43       <year>2001</year>
  44       <holder>Internet Software Consortium.</holder>
  45     </copyright>
  46   </docinfo>
  47
  48   <refnamediv>
  49     <refname>lwres_getrrsetbyname</refname>
  50     <refname>lwres_freerrset</refname>
  51     <refpurpose>retrieve DNS records</refpurpose>
  52   </refnamediv>
  53   <refsynopsisdiv>
  54     <funcsynopsis>
  55 <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
  56 <funcprototype>
  57         <funcdef>
  58 int
  59 <function>lwres_getrrsetbyname</function></funcdef>
  60         <paramdef>const char *<parameter>hostname</parameter></paramdef>
  61         <paramdef>unsigned int <parameter>rdclass</parameter></paramdef>
  62         <paramdef>unsigned int <parameter>rdtype</parameter></paramdef>
  63         <paramdef>unsigned int <parameter>flags</parameter></paramdef>
  64         <paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef>
  65         </funcprototype>
  66 <funcprototype>
  67         <funcdef>
  68 void
  69 <function>lwres_freerrset</function></funcdef>
  70         <paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef>
  71       </funcprototype>
  72 </funcsynopsis>
  73
  74     <para>
  75       The following structures are used:
  76     </para>
  77     <para><programlisting>
  78 struct  rdatainfo {
  79         unsigned int            rdi_length;     /* length of data */
  80         unsigned char           *rdi_data;      /* record data */
  81 };
  82 </programlisting>
  83     </para>
  84     <para><programlisting>
  85 struct  rrsetinfo {
  86         unsigned int            rri_flags;      /* RRSET_VALIDATED... */
  87         unsigned int            rri_rdclass;    /* class number */
  88         unsigned int            rri_rdtype;     /* RR type number */
  89         unsigned int            rri_ttl;        /* time to live */
  90         unsigned int            rri_nrdatas;    /* size of rdatas array */
  91         unsigned int            rri_nsigs;      /* size of sigs array */
  92         char                    *rri_name;      /* canonical name */
  93         struct rdatainfo        *rri_rdatas;    /* individual records */
  94         struct rdatainfo        *rri_sigs;      /* individual signatures */
  95 };
  96 </programlisting>
  97     </para>
  98   </refsynopsisdiv>
  99
 100   <refsect1>
 101     <title>DESCRIPTION</title>
 102     <para><function>lwres_getrrsetbyname()</function>
 103       gets a set of resource records associated with a
 104       <parameter>hostname</parameter>, <parameter>class</parameter>,
 105       and <parameter>type</parameter>.
 106       <parameter>hostname</parameter> is a pointer a to
 107       null-terminated string.  The <parameter>flags</parameter> field
 108       is currently unused and must be zero.
 109     </para>
 110     <para>
 111       After a successful call to
 112       <function>lwres_getrrsetbyname()</function>,
 113       <parameter>*res</parameter> is a pointer to an
 114       <type>rrsetinfo</type> structure, containing a list of one or
 115       more <type>rdatainfo</type> structures containing resource
 116       records and potentially another list of <type>rdatainfo</type>
 117       structures containing SIG resource records associated with those
 118       records.  The members <constant>rri_rdclass</constant> and
 119       <constant>rri_rdtype</constant> are copied from the parameters.
 120       <constant>rri_ttl</constant> and <constant>rri_name</constant>
 121       are properties of the obtained rrset.  The resource records
 122       contained in <constant>rri_rdatas</constant> and
 123       <constant>rri_sigs</constant> are in uncompressed DNS wire
 124       format.  Properties of the rdataset are represented in the
 125       <constant>rri_flags</constant> bitfield.  If the RRSET_VALIDATED
 126       bit is set, the data has been DNSSEC validated and the
 127       signatures verified.
 128     </para>
 129     <para>
 130       All of the information returned by
 131       <function>lwres_getrrsetbyname()</function> is dynamically
 132       allocated: the <constant>rrsetinfo</constant> and
 133       <constant>rdatainfo</constant> structures, and the canonical
 134       host name strings pointed to by the
 135       <constant>rrsetinfo</constant>structure.
 136
 137       Memory allocated for the dynamically allocated structures
 138       created by a successful call to
 139       <function>lwres_getrrsetbyname()</function> is released by
 140       <function>lwres_freerrset()</function>.
 141
 142       <parameter>rrset</parameter> is a pointer to a <type>struct
 143       rrset</type> created by a call to
 144       <function>lwres_getrrsetbyname()</function>.
 145     </para>
 146     <para></para>
 147   </refsect1>
 148   <refsect1>
 149     <title>RETURN VALUES</title>
 150     <para><function>lwres_getrrsetbyname()</function>
 151       returns zero on success, and one of the following error codes if
 152       an error occurred:
 153       <variablelist>
 154
 155         <varlistentry>
 156           <term><constant>ERRSET_NONAME</constant></term>
 157           <listitem>
 158             <para>
 159               the name does not exist
 160             </para>
 161           </listitem>
 162         </varlistentry>
 163
 164         <varlistentry>
 165           <term><constant>ERRSET_NODATA</constant></term>
 166           <listitem>
 167             <para>
 168               the name exists, but does not have data of the desired type
 169             </para>
 170           </listitem>
 171         </varlistentry>
 172
 173         <varlistentry>
 174           <term><constant>ERRSET_NOMEMORY</constant></term>
 175           <listitem>
 176             <para>
 177               memory could not be allocated
 178             </para>
 179           </listitem>
 180         </varlistentry>
 181
 182         <varlistentry>
 183           <term><constant>ERRSET_INVAL</constant></term>
 184           <listitem>
 185             <para>
 186               a parameter is invalid
 187             </para>
 188           </listitem>
 189         </varlistentry>
 190
 191         <varlistentry>
 192           <term><constant>ERRSET_FAIL</constant></term>
 193           <listitem>
 194             <para>
 195               other failure
 196             </para>
 197           </listitem>
 198         </varlistentry>
 199
 200         <varlistentry>
 201           <term><constant/></term>
 202           <listitem>
 203             <para></para>
 204           </listitem>
 205         </varlistentry>
 206
 207       </variablelist>
 208
 209     </para>
 210   </refsect1>
 211   <refsect1>
 212     <title>SEE ALSO</title>
 213     <para><citerefentry>
 214         <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 215       </citerefentry>.
 216     </para>
 217
 218   </refsect1>
 219 </refentry><!--
 220  - Local variables:
 221  - mode: sgml
 222  - End:
 223 -->