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

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