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