src/libfreeswan/liblwres/man/lwres_getipnode.docbook

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <!--
   3  - Copyright (C) 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and 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 INTERNET SOFTWARE CONSORTIUM
  10  - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  11  - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  12  - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  13  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  14  - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  15  - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  16  - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 -->
  18
  19 <!-- $Id: lwres_getipnode.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
  20
  21 <refentry>
  22
  23 <refentryinfo>
  24 <date>Jun 30, 2000</date>
  25 </refentryinfo>
  26
  27 <refmeta>
  28 <refentrytitle>lwres_getipnode</refentrytitle>
  29 <manvolnum>3</manvolnum>
  30 <refmiscinfo>BIND9</refmiscinfo>
  31 </refmeta>
  32
  33 <refnamediv>
  34 <refname>lwres_getipnodebyname</refname>
  35 <refname>lwres_getipnodebyaddr</refname>
  36 <refname>lwres_freehostent</refname>
  37 <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
  38 </refnamediv>
  39 <refsynopsisdiv>
  40 <funcsynopsis>
  41 <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
  42 <funcprototype>
  43 <funcdef>
  44 struct hostent *
  45 <function>lwres_getipnodebyname</function></funcdef>
  46 <paramdef>const char *name</paramdef>
  47 <paramdef>int af</paramdef>
  48 <paramdef>int flags</paramdef>
  49 <paramdef>int *error_num</paramdef>
  50 </funcprototype>
  51 <funcprototype>
  52 <funcdef>
  53 struct hostent *
  54 <function>lwres_getipnodebyaddr</function></funcdef>
  55 <paramdef>const void *src</paramdef>
  56 <paramdef>size_t len</paramdef>
  57 <paramdef>int af</paramdef>
  58 <paramdef>int *error_num</paramdef>
  59 </funcprototype>
  60 <funcprototype>
  61 <funcdef>
  62 void
  63 <function>lwres_freehostent</function></funcdef>
  64 <paramdef>struct hostent *he</paramdef>
  65 </funcprototype>
  66 </funcsynopsis>
  67 </refsynopsisdiv>
  68
  69 <refsect1>
  70 <title>DESCRIPTION</title>
  71
  72 <para>
  73 These functions perform thread safe, protocol independent
  74 nodename-to-address and address-to-nodename
  75 translation as defined in RFC2553.
  76 </para>
  77
  78 <para>
  79 They use a
  80 <type>struct hostent</type>
  81 which is defined in
  82 <filename>namedb.h</filename>:
  83 <programlisting>
  84 struct  hostent {
  85         char    *h_name;        /* official name of host */
  86         char    **h_aliases;    /* alias list */
  87         int     h_addrtype;     /* host address type */
  88         int     h_length;       /* length of address */
  89         char    **h_addr_list;  /* list of addresses from name server */
  90 };
  91 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
  92 </programlisting>
  93 </para>
  94
  95 <para>
  96 The members of this structure are:
  97 <variablelist>
  98 <varlistentry><term><constant>h_name</constant></term>
  99 <listitem>
 100 <para>
 101 The official (canonical) name of the host.
 102 </para>
 103 </listitem></varlistentry>
 104 <varlistentry><term><constant>h_aliases</constant></term>
 105 <listitem>
 106 <para>
 107 A NULL-terminated array of alternate names (nicknames) for the host.
 108 </para>
 109 </listitem></varlistentry>
 110 <varlistentry><term><constant>h_addrtype</constant></term>
 111 <listitem>
 112 <para>
 113 The type of address being returned - usually
 114 <type>PF_INET</type>
 115 or
 116 <type>PF_INET6</type>.
 117
 118 </para>
 119 </listitem></varlistentry>
 120 <varlistentry><term><constant>h_length</constant></term>
 121 <listitem>
 122 <para>
 123 The length of the address in bytes.
 124 </para>
 125 </listitem></varlistentry>
 126 <varlistentry><term><constant>h_addr_list</constant></term>
 127 <listitem>
 128 <para>
 129 A
 130 <type>NULL</type>
 131 terminated array of network addresses for the host.
 132 Host addresses are returned in network byte order.
 133 </para>
 134 </listitem></varlistentry>
 135 </variablelist>
 136 </para>
 137 <para>
 138 <function>lwres_getipnodebyname()</function>
 139 looks up addresses of protocol family
 140 <parameter>af</parameter>
 141
 142 for the hostname
 143 <parameter>name</parameter>.
 144
 145 The
 146 <parameter>flags</parameter>
 147 parameter contains ORed flag bits to
 148 specify the types of addresses that are searched
 149 for, and the types of addresses that are returned.
 150 The flag bits are:
 151 <variablelist>
 152 <varlistentry><term><constant>AI_V4MAPPED</constant></term>
 153 <listitem>
 154 <para>
 155 This is used with an
 156 <parameter>af</parameter>
 157 of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
 158 IPv6 addresses.
 159 </para>
 160 </listitem></varlistentry>
 161 <varlistentry><term><constant>AI_ALL</constant></term>
 162 <listitem>
 163 <para>
 164 This is used with an
 165 <parameter>af</parameter>
 166 of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
 167 If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
 168 IPv6 addresses.
 169 </para>
 170 </listitem></varlistentry>
 171 <varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
 172 <listitem>
 173 <para>
 174 Only return an IPv6 or IPv4 address if here is an active network
 175 interface of that type.  This is not currently implemented
 176 in the BIND 9 lightweight resolver, and the flag is ignored.
 177 </para>
 178 </listitem></varlistentry>
 179 <varlistentry><term><constant>AI_DEFAULT</constant></term>
 180 <listitem>
 181 <para>
 182 This default sets the
 183 <constant>AI_V4MAPPED</constant>
 184 and
 185 <constant>AI_ADDRCONFIG</constant>
 186 flag bits.
 187 </para>
 188 </listitem></varlistentry>
 189 </variablelist>
 190 </para>
 191 <para>
 192 <function>lwres_getipnodebyaddr()</function>
 193 performs a reverse lookup
 194 of address
 195 <parameter>src</parameter>
 196 which is
 197 <parameter>len</parameter>
 198 bytes long.
 199 <parameter>af</parameter>
 200 denotes the protocol family, typically
 201 <type>PF_INET</type>
 202 or
 203 <type>PF_INET6</type>.
 204
 205 </para>
 206 <para>
 207 <function>lwres_freehostent()</function>
 208 releases all the memory associated with
 209 the
 210 <type>struct hostent</type>
 211 pointer
 212 <parameter>he</parameter>.
 213
 214 Any memory allocated for the
 215 <constant>h_name</constant>,
 216
 217 <constant>h_addr_list</constant>
 218 and
 219 <constant>h_aliases</constant>
 220 is freed, as is the memory for the
 221 <type>hostent</type>
 222 structure itself.
 223 </para>
 224 </refsect1>
 225 <refsect1>
 226 <title>RETURN VALUES</title>
 227 <para>
 228 If an error occurs,
 229 <function>lwres_getipnodebyname()</function>
 230 and
 231 <function>lwres_getipnodebyaddr()</function>
 232 set
 233 <parameter>*error_num</parameter>
 234 to an approriate error code and the function returns a
 235 <type>NULL</type>
 236 pointer.
 237 The error codes and their meanings are defined in
 238 <filename>&lt;lwres/netdb.h&gt;</filename>:
 239 <variablelist>
 240 <varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
 241 <listitem>
 242 <para>
 243 No such host is known.
 244 </para>
 245 </listitem></varlistentry>
 246 <varlistentry><term><constant>NO_ADDRESS</constant></term>
 247 <listitem>
 248 <para>
 249 The server recognised the request and the name but no address is
 250 available.  Another type of request to the name server for the
 251 domain might return an answer.
 252 </para>
 253 </listitem></varlistentry>
 254 <varlistentry><term><constant>TRY_AGAIN</constant></term>
 255 <listitem>
 256 <para>
 257 A temporary and possibly transient error occurred, such as a
 258 failure of a server to respond.  The request may succeed if
 259 retried.
 260 </para>
 261 </listitem></varlistentry>
 262 <varlistentry><term><constant>NO_RECOVERY</constant></term>
 263 <listitem>
 264 <para>
 265 An unexpected failure occurred, and retrying the request
 266 is pointless.
 267 </para>
 268 </listitem></varlistentry>
 269 </variablelist>
 270 </para>
 271 <para>
 272 <citerefentry>
 273 <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
 274 </manvolnum>
 275 </citerefentry>
 276 translates these error codes to suitable error messages.
 277 </para>
 278 </refsect1>
 279 <refsect1>
 280 <title>SEE ALSO</title>
 281 <para>
 282 <citerefentry>
 283 <refentrytitle>RFC2553</refentrytitle>
 284 </citerefentry>,
 285
 286 <citerefentry>
 287 <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 288 </citerefentry>,
 289
 290 <citerefentry>
 291 <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
 292 </citerefentry>,
 293
 294 <citerefentry>
 295 <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
 296 </citerefentry>,
 297
 298 <citerefentry>
 299 <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
 300 </citerefentry>,
 301
 302 <citerefentry>
 303 <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
 304 </citerefentry>.
 305 </para>
 306 </refsect1>
 307 </refentry>