/contrib/bind9/lib/lwres/man/lwres_getipnode.docbook
Unknown | 332 lines | 314 code | 18 blank | 0 comment | 0 complexity | 8ac335fd07933933ffffbb0eee8cca33 MD5 | raw file
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 "—">]> 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 <lwres/netdb.h></funcsynopsisinfo> 59<funcprototype> 60 <funcdef> 61struct 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> 70struct 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> 79void 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> 102struct 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><lwres/netdb.h></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-->