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