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, 2014 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<refentry> 22 23 <refentryinfo> 24 <date>June 18, 2007</date> 25 </refentryinfo> 26 27 <refmeta> 28 <refentrytitle>lwres_getipnode</refentrytitle> 29 <manvolnum>3</manvolnum> 30 <refmiscinfo>BIND9</refmiscinfo> 31 </refmeta> 32 33 <docinfo> 34 <copyright> 35 <year>2004</year> 36 <year>2005</year> 37 <year>2007</year> 38 <year>2014</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 <lwres/netdb.h></funcsynopsisinfo> 58<funcprototype> 59 <funcdef> 60struct 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> 69struct 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> 78void 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> 101struct 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><lwres/netdb.h></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--> 332