contrib/bind9/lib/lwres/man/lwres_getipnode.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, 2003  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_getipnode.docbook,v 1.12 2007/06/18 23:47:51 tbox Exp $ -->
  22 <refentry>
  23
  24   <refentryinfo>
  25     <date>Jun 30, 2000</date>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>lwres_getipnode</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       <year>2003</year>
  45       <holder>Internet Software Consortium.</holder>
  46     </copyright>
  47   </docinfo>
  48
  49   <refnamediv>
  50     <refname>lwres_getipnodebyname</refname>
  51     <refname>lwres_getipnodebyaddr</refname>
  52     <refname>lwres_freehostent</refname>
  53     <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
  54   </refnamediv>
  55   <refsynopsisdiv>
  56     <funcsynopsis>
  57 <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
  58 <funcprototype>
  59         <funcdef>
  60 struct hostent *
  61 <function>lwres_getipnodebyname</function></funcdef>
  62         <paramdef>const char *<parameter>name</parameter></paramdef>
  63         <paramdef>int <parameter>af</parameter></paramdef>
  64         <paramdef>int <parameter>flags</parameter></paramdef>
  65         <paramdef>int *<parameter>error_num</parameter></paramdef>
  66         </funcprototype>
  67 <funcprototype>
  68         <funcdef>
  69 struct hostent *
  70 <function>lwres_getipnodebyaddr</function></funcdef>
  71         <paramdef>const void *<parameter>src</parameter></paramdef>
  72         <paramdef>size_t <parameter>len</parameter></paramdef>
  73         <paramdef>int <parameter>af</parameter></paramdef>
  74         <paramdef>int *<parameter>error_num</parameter></paramdef>
  75         </funcprototype>
  76 <funcprototype>
  77         <funcdef>
  78 void
  79 <function>lwres_freehostent</function></funcdef>
  80         <paramdef>struct hostent *<parameter>he</parameter></paramdef>
  81       </funcprototype>
  82 </funcsynopsis>
  83   </refsynopsisdiv>
  84
  85   <refsect1>
  86     <title>DESCRIPTION</title>
  87
  88     <para>
  89       These functions perform thread safe, protocol independent
  90       nodename-to-address and address-to-nodename
  91       translation as defined in RFC2553.
  92     </para>
  93
  94     <para>
  95       They use a
  96       <type>struct hostent</type>
  97       which is defined in
  98       <filename>namedb.h</filename>:
  99     </para>
 100     <para><programlisting>
 101 struct  hostent {
 102         char    *h_name;        /* official name of host */
 103         char    **h_aliases;    /* alias list */
 104         int     h_addrtype;     /* host address type */
 105         int     h_length;       /* length of address */
 106         char    **h_addr_list;  /* list of addresses from name server */
 107 };
 108 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 109 </programlisting>
 110     </para>
 111
 112     <para>
 113       The members of this structure are:
 114       <variablelist>
 115         <varlistentry>
 116           <term><constant>h_name</constant></term>
 117           <listitem>
 118             <para>
 119               The official (canonical) name of the host.
 120             </para>
 121           </listitem>
 122         </varlistentry>
 123         <varlistentry>
 124           <term><constant>h_aliases</constant></term>
 125           <listitem>
 126             <para>
 127               A NULL-terminated array of alternate names (nicknames) for the
 128               host.
 129             </para>
 130           </listitem>
 131         </varlistentry>
 132         <varlistentry>
 133           <term><constant>h_addrtype</constant></term>
 134           <listitem>
 135             <para>
 136               The type of address being returned - usually
 137               <type>PF_INET</type>
 138               or
 139               <type>PF_INET6</type>.
 140
 141             </para>
 142           </listitem>
 143         </varlistentry>
 144         <varlistentry>
 145           <term><constant>h_length</constant></term>
 146           <listitem>
 147             <para>
 148               The length of the address in bytes.
 149             </para>
 150           </listitem>
 151         </varlistentry>
 152         <varlistentry>
 153           <term><constant>h_addr_list</constant></term>
 154           <listitem>
 155             <para>
 156               A
 157               <type>NULL</type>
 158               terminated array of network addresses for the host.
 159               Host addresses are returned in network byte order.
 160             </para>
 161           </listitem>
 162         </varlistentry>
 163       </variablelist>
 164     </para>
 165
 166     <para><function>lwres_getipnodebyname()</function>
 167       looks up addresses of protocol family <parameter>af</parameter>
 168       for the hostname <parameter>name</parameter>.  The
 169       <parameter>flags</parameter> parameter contains ORed flag bits
 170       to specify the types of addresses that are searched for, and the
 171       types of addresses that are returned.  The flag bits are:
 172
 173       <variablelist>
 174         <varlistentry>
 175           <term><constant>AI_V4MAPPED</constant></term>
 176           <listitem>
 177             <para>
 178               This is used with an
 179               <parameter>af</parameter>
 180               of AF_INET6, and causes IPv4 addresses to be returned as
 181               IPv4-mapped
 182               IPv6 addresses.
 183             </para>
 184           </listitem>
 185         </varlistentry>
 186         <varlistentry>
 187           <term><constant>AI_ALL</constant></term>
 188           <listitem>
 189             <para>
 190               This is used with an
 191               <parameter>af</parameter>
 192               of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
 193               be returned.
 194               If AI_V4MAPPED is also set, the IPv4 addresses are return as
 195               mapped
 196               IPv6 addresses.
 197             </para>
 198           </listitem>
 199         </varlistentry>
 200         <varlistentry>
 201           <term><constant>AI_ADDRCONFIG</constant></term>
 202           <listitem>
 203             <para>
 204               Only return an IPv6 or IPv4 address if here is an active network
 205               interface of that type.  This is not currently implemented
 206               in the BIND 9 lightweight resolver, and the flag is ignored.
 207             </para>
 208           </listitem>
 209         </varlistentry>
 210         <varlistentry>
 211           <term><constant>AI_DEFAULT</constant></term>
 212           <listitem>
 213             <para>
 214               This default sets the
 215               <constant>AI_V4MAPPED</constant>
 216               and
 217               <constant>AI_ADDRCONFIG</constant>
 218               flag bits.
 219             </para>
 220           </listitem>
 221         </varlistentry>
 222       </variablelist>
 223     </para>
 224
 225     <para><function>lwres_getipnodebyaddr()</function>
 226       performs a reverse lookup of address <parameter>src</parameter>
 227       which is <parameter>len</parameter> bytes long.
 228       <parameter>af</parameter> denotes the protocol family, typically
 229       <type>PF_INET</type> or <type>PF_INET6</type>.
 230     </para>
 231     <para><function>lwres_freehostent()</function>
 232       releases all the memory associated with the <type>struct
 233       hostent</type> pointer <parameter>he</parameter>.  Any memory
 234       allocated for the <constant>h_name</constant>,
 235       <constant>h_addr_list</constant> and
 236       <constant>h_aliases</constant> is freed, as is the memory for
 237       the <type>hostent</type> structure itself.
 238     </para>
 239   </refsect1>
 240   <refsect1>
 241     <title>RETURN VALUES</title>
 242     <para>
 243       If an error occurs,
 244       <function>lwres_getipnodebyname()</function>
 245       and
 246       <function>lwres_getipnodebyaddr()</function>
 247       set
 248       <parameter>*error_num</parameter>
 249       to an appropriate error code and the function returns a
 250       <type>NULL</type>
 251       pointer.
 252       The error codes and their meanings are defined in
 253       <filename>&lt;lwres/netdb.h&gt;</filename>:
 254       <variablelist>
 255         <varlistentry>
 256           <term><constant>HOST_NOT_FOUND</constant></term>
 257           <listitem>
 258             <para>
 259               No such host is known.
 260             </para>
 261           </listitem>
 262         </varlistentry>
 263         <varlistentry>
 264           <term><constant>NO_ADDRESS</constant></term>
 265           <listitem>
 266             <para>
 267               The server recognised the request and the name but no address is
 268               available.  Another type of request to the name server for the
 269               domain might return an answer.
 270             </para>
 271           </listitem>
 272         </varlistentry>
 273         <varlistentry>
 274           <term><constant>TRY_AGAIN</constant></term>
 275           <listitem>
 276             <para>
 277               A temporary and possibly transient error occurred, such as a
 278               failure of a server to respond.  The request may succeed if
 279               retried.
 280             </para>
 281           </listitem>
 282         </varlistentry>
 283         <varlistentry>
 284           <term><constant>NO_RECOVERY</constant></term>
 285           <listitem>
 286             <para>
 287               An unexpected failure occurred, and retrying the request
 288               is pointless.
 289             </para>
 290           </listitem>
 291         </varlistentry>
 292       </variablelist>
 293     </para>
 294     <para><citerefentry>
 295         <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
 296       </citerefentry>
 297       translates these error codes to suitable error messages.
 298     </para>
 299   </refsect1>
 300   <refsect1>
 301     <title>SEE ALSO</title>
 302     <para><citerefentry>
 303         <refentrytitle>RFC2553</refentrytitle>
 304       </citerefentry>,
 305
 306       <citerefentry>
 307         <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 308       </citerefentry>,
 309
 310       <citerefentry>
 311         <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
 312       </citerefentry>,
 313
 314       <citerefentry>
 315         <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
 316       </citerefentry>,
 317
 318       <citerefentry>
 319         <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
 320       </citerefentry>,
 321
 322       <citerefentry>
 323         <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
 324       </citerefentry>.
 325     </para>
 326   </refsect1>
 327 </refentry><!--
 328  - Local variables:
 329  - mode: sgml
 330  - End:
 331 -->