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