/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.docbook
Unknown | 388 lines | 354 code | 34 blank | 0 comment | 0 complexity | d360cbef8ac9daef29f720805148de3f 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_getaddrinfo</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_getaddrinfo</refname> 52 <refname>lwres_freeaddrinfo</refname> 53 <refpurpose>socket address structure to host and service name</refpurpose> 54 </refnamediv> 55 <refsynopsisdiv> 56 <funcsynopsis> 57<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> 58<funcprototype> 59 <funcdef> 60int 61<function>lwres_getaddrinfo</function></funcdef> 62 <paramdef>const char *<parameter>hostname</parameter></paramdef> 63 <paramdef>const char *<parameter>servname</parameter></paramdef> 64 <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef> 65 <paramdef>struct addrinfo **<parameter>res</parameter></paramdef> 66 </funcprototype> 67<funcprototype> 68 <funcdef> 69void 70<function>lwres_freeaddrinfo</function></funcdef> 71 <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef> 72 </funcprototype> 73</funcsynopsis> 74 75 <para> 76 If the operating system does not provide a 77 <type>struct addrinfo</type>, 78 the following structure is used: 79 </para> 80 <para><programlisting> 81struct addrinfo { 82 int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ 83 int ai_family; /* PF_xxx */ 84 int ai_socktype; /* SOCK_xxx */ 85 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 86 size_t ai_addrlen; /* length of ai_addr */ 87 char *ai_canonname; /* canonical name for hostname */ 88 struct sockaddr *ai_addr; /* binary address */ 89 struct addrinfo *ai_next; /* next structure in linked list */ 90}; 91</programlisting> 92 </para> 93 94 </refsynopsisdiv> 95 96 <refsect1> 97 <title>DESCRIPTION</title> 98 99 <para><function>lwres_getaddrinfo()</function> 100 is used to get a list of IP addresses and port numbers for host 101 <parameter>hostname</parameter> and service 102 <parameter>servname</parameter>. 103 104 The function is the lightweight resolver's implementation of 105 <function>getaddrinfo()</function> as defined in RFC2133. 106 <parameter>hostname</parameter> and 107 <parameter>servname</parameter> are pointers to null-terminated 108 strings or <type>NULL</type>. 109 110 <parameter>hostname</parameter> is either a host name or a 111 numeric host address string: a dotted decimal IPv4 address or an 112 IPv6 address. <parameter>servname</parameter> is either a 113 decimal port number or a service name as listed in 114 <filename>/etc/services</filename>. 115 </para> 116 117 <para><parameter>hints</parameter> 118 is an optional pointer to a 119 <type>struct addrinfo</type>. 120 This structure can be used to provide hints concerning the type of 121 socket 122 that the caller supports or wishes to use. 123 The caller can supply the following structure elements in 124 <parameter>*hints</parameter>: 125 126 <variablelist> 127 <varlistentry> 128 <term><constant>ai_family</constant></term> 129 <listitem> 130 <para> 131 The protocol family that should be used. 132 When 133 <constant>ai_family</constant> 134 is set to 135 <type>PF_UNSPEC</type>, 136 it means the caller will accept any protocol family supported by 137 the 138 operating system. 139 </para> 140 </listitem> 141 </varlistentry> 142 <varlistentry> 143 <term><constant>ai_socktype</constant></term> 144 <listitem> 145 <para> 146 denotes the type of socket — 147 <type>SOCK_STREAM</type>, 148 <type>SOCK_DGRAM</type> 149 or 150 <type>SOCK_RAW</type> 151 — that is wanted. 152 When 153 <constant>ai_socktype</constant> 154 is zero the caller will accept any socket type. 155 </para> 156 </listitem> 157 </varlistentry> 158 <varlistentry> 159 <term><constant>ai_protocol</constant></term> 160 <listitem> 161 <para> 162 indicates which transport protocol is wanted: IPPROTO_UDP or 163 IPPROTO_TCP. 164 If 165 <constant>ai_protocol</constant> 166 is zero the caller will accept any protocol. 167 </para> 168 </listitem> 169 </varlistentry> 170 <varlistentry> 171 <term><constant>ai_flags</constant></term> 172 <listitem> 173 <para> 174 Flag bits. 175 If the 176 <type>AI_CANONNAME</type> 177 bit is set, a successful call to 178 <function>lwres_getaddrinfo()</function> 179 will return a null-terminated string containing the canonical 180 name 181 of the specified hostname in 182 <constant>ai_canonname</constant> 183 of the first 184 <type>addrinfo</type> 185 structure returned. 186 Setting the 187 <type>AI_PASSIVE</type> 188 bit indicates that the returned socket address structure is 189 intended 190 for used in a call to 191 <citerefentry> 192 <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum> 193 </citerefentry>. 194 195 In this case, if the hostname argument is a 196 <type>NULL</type> 197 pointer, then the IP address portion of the socket 198 address structure will be set to 199 <type>INADDR_ANY</type> 200 for an IPv4 address or 201 <type>IN6ADDR_ANY_INIT</type> 202 for an IPv6 address. 203 </para> 204 <para> 205 When 206 <constant>ai_flags</constant> 207 does not set the 208 <type>AI_PASSIVE</type> 209 bit, the returned socket address structure will be ready 210 for use in a call to 211 <citerefentry> 212 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> 213 </citerefentry> 214 for a connection-oriented protocol or 215 <citerefentry> 216 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> 217 </citerefentry>, 218 219 <citerefentry> 220 <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> 221 </citerefentry>, 222 223 or 224 <citerefentry> 225 <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum> 226 </citerefentry> 227 if a connectionless protocol was chosen. 228 The IP address portion of the socket address structure will be 229 set to the loopback address if 230 <parameter>hostname</parameter> 231 is a 232 <type>NULL</type> 233 pointer and 234 <type>AI_PASSIVE</type> 235 is not set in 236 <constant>ai_flags</constant>. 237 </para> 238 <para> 239 If 240 <constant>ai_flags</constant> 241 is set to 242 <type>AI_NUMERICHOST</type> 243 it indicates that 244 <parameter>hostname</parameter> 245 should be treated as a numeric string defining an IPv4 or IPv6 246 address 247 and no name resolution should be attempted. 248 </para> 249 </listitem> 250 </varlistentry> 251 </variablelist> 252 </para> 253 254 <para> 255 All other elements of the <type>struct addrinfo</type> passed 256 via <parameter>hints</parameter> must be zero. 257 </para> 258 259 <para> 260 A <parameter>hints</parameter> of <type>NULL</type> is 261 treated as if 262 the caller provided a <type>struct addrinfo</type> initialized to zero 263 with <constant>ai_family</constant>set to 264 <constant>PF_UNSPEC</constant>. 265 </para> 266 267 <para> 268 After a successful call to 269 <function>lwres_getaddrinfo()</function>, 270 <parameter>*res</parameter> 271 is a pointer to a linked list of one or more 272 <type>addrinfo</type> 273 structures. 274 Each 275 <type>struct addrinfo</type> 276 in this list cn be processed by following 277 the 278 <constant>ai_next</constant> 279 pointer, until a 280 <type>NULL</type> 281 pointer is encountered. 282 The three members 283 <constant>ai_family</constant>, 284 <constant>ai_socktype</constant>, 285 and 286 <constant>ai_protocol</constant> 287 in each 288 returned 289 <type>addrinfo</type> 290 structure contain the corresponding arguments for a call to 291 <citerefentry> 292 <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum> 293 </citerefentry>. 294 For each 295 <type>addrinfo</type> 296 structure in the list, the 297 <constant>ai_addr</constant> 298 member points to a filled-in socket address structure of length 299 <constant>ai_addrlen</constant>. 300 </para> 301 302 <para> 303 All of the information returned by 304 <function>lwres_getaddrinfo()</function> 305 is dynamically allocated: the addrinfo structures, and the socket 306 address structures and canonical host name strings pointed to by the 307 <constant>addrinfo</constant>structures. 308 Memory allocated for the dynamically allocated structures created by 309 a successful call to 310 <function>lwres_getaddrinfo()</function> 311 is released by 312 <function>lwres_freeaddrinfo()</function>. 313 <parameter>ai</parameter> 314 is a pointer to a 315 <type>struct addrinfo</type> 316 created by a call to 317 <function>lwres_getaddrinfo()</function>. 318 </para> 319 320 </refsect1> 321 322 <refsect1> 323 <title>RETURN VALUES</title> 324 325 <para><function>lwres_getaddrinfo()</function> 326 returns zero on success or one of the error codes listed in 327 <citerefentry> 328 <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum> 329 </citerefentry> 330 if an error occurs. If both <parameter>hostname</parameter> and 331 <parameter>servname</parameter> are <type>NULL</type> 332 <function>lwres_getaddrinfo()</function> returns 333 <errorcode>EAI_NONAME</errorcode>. 334 </para> 335 </refsect1> 336 <refsect1> 337 <title>SEE ALSO</title> 338 <para><citerefentry> 339 <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> 340 </citerefentry>, 341 342 <citerefentry> 343 <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> 344 </citerefentry>, 345 346 <citerefentry> 347 <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum> 348 </citerefentry>, 349 350 <citerefentry> 351 <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum> 352 </citerefentry>, 353 354 <citerefentry> 355 <refentrytitle>RFC2133</refentrytitle> 356 </citerefentry>, 357 358 <citerefentry> 359 <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum> 360 </citerefentry>, 361 362 <citerefentry> 363 <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum> 364 </citerefentry>, 365 366 <citerefentry> 367 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> 368 </citerefentry>, 369 370 <citerefentry> 371 <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> 372 </citerefentry>, 373 374 <citerefentry> 375 <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum> 376 </citerefentry>, 377 378 <citerefentry> 379 <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum> 380 </citerefentry>. 381 </para> 382 383 </refsect1> 384</refentry><!-- 385 - Local variables: 386 - mode: sgml 387 - End: 388-->