lib/libc/net/getaddrinfo.3

   1 .\"     $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
   2 .\"     $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
   3 .\"     $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.29 2005/01/23 16:02:48 gnn Exp $
   4 .\"     $DragonFly: src/lib/libc/net/getaddrinfo.3,v 1.7 2008/05/22 06:50:14 hasso Exp $
   5 .\"
   6 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   7 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   8 .\"
   9 .\" Permission to use, copy, modify, and distribute this software for any
  10 .\" purpose with or without fee is hereby granted, provided that the above
  11 .\" copyright notice and this permission notice appear in all copies.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  14 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  15 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  16 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  17 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  18 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  19 .\" PERFORMANCE OF THIS SOFTWARE.
  20 .\"
  21 .Dd May 22, 2008
  22 .Dt GETADDRINFO 3
  23 .Os
  24 .Sh NAME
  25 .Nm getaddrinfo ,
  26 .Nm freeaddrinfo
  27 .Nd socket address structure to host and service name
  28 .Sh LIBRARY
  29 .Lb libc
  30 .Sh SYNOPSIS
  31 .In sys/types.h
  32 .In sys/socket.h
  33 .In netdb.h
  34 .Ft int
  35 .Fn getaddrinfo "const char *hostname" "const char *servname" \
  36     "const struct addrinfo *hints" "struct addrinfo **res"
  37 .Ft void
  38 .Fn freeaddrinfo "struct addrinfo *ai"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn getaddrinfo
  42 function is used to get a list of
  43 .Tn IP
  44 addresses and port numbers for host
  45 .Fa hostname
  46 and service
  47 .Fa servname .
  48 It is a replacement for and provides more flexibility than the
  49 .Xr gethostbyname 3
  50 and
  51 .Xr getservbyname 3
  52 functions.
  53 .Pp
  54 The
  55 .Fa hostname
  56 and
  57 .Fa servname
  58 arguments are either pointers to NUL-terminated strings or the null pointer.
  59 An acceptable value for
  60 .Fa hostname
  61 is either a valid host name or a numeric host address string consisting
  62 of a dotted decimal IPv4 address or an IPv6 address.
  63 The
  64 .Fa servname
  65 is either a decimal port number or a service name listed in
  66 .Xr services 5 .
  67 At least one of
  68 .Fa hostname
  69 and
  70 .Fa servname
  71 must be non-null.
  72 .Pp
  73 .Fa hints
  74 is an optional pointer to a
  75 .Li struct addrinfo ,
  76 as defined by
  77 .In netdb.h :
  78 .Bd -literal
  79 struct addrinfo {
  80         int ai_flags;           /* input flags */
  81         int ai_family;          /* protocol family for socket */
  82         int ai_socktype;        /* socket type */
  83         int ai_protocol;        /* protocol for socket */
  84         socklen_t ai_addrlen;   /* length of socket-address */
  85         struct sockaddr *ai_addr; /* socket-address for socket */
  86         char *ai_canonname;     /* canonical name for service location */
  87         struct addrinfo *ai_next; /* pointer to next in list */
  88 };
  89 .Ed
  90 .Pp
  91 This structure can be used to provide hints concerning the type of socket
  92 that the caller supports or wishes to use.
  93 The caller can supply the following structure elements in
  94 .Fa hints :
  95 .Bl -tag -width "ai_socktypeXX"
  96 .It Fa ai_family
  97 The protocol family that should be used.
  98 When
  99 .Fa ai_family
 100 is set to
 101 .Dv PF_UNSPEC ,
 102 it means the caller will accept any protocol family supported by the
 103 operating system.
 104 .It Fa ai_socktype
 105 Denotes the type of socket that is wanted:
 106 .Dv SOCK_STREAM ,
 107 .Dv SOCK_DGRAM ,
 108 or
 109 .Dv SOCK_RAW .
 110 When
 111 .Fa ai_socktype
 112 is zero the caller will accept any socket type.
 113 .It Fa ai_protocol
 114 Indicates which transport protocol is desired,
 115 .Dv IPPROTO_UDP
 116 or
 117 .Dv IPPROTO_TCP .
 118 If
 119 .Fa ai_protocol
 120 is zero the caller will accept any protocol.
 121 .It Fa ai_flags
 122 .Fa ai_flags
 123 is formed by
 124 .Tn OR Ns 'ing
 125 the following values:
 126 .Bl -tag -width "AI_CANONNAMEXX"
 127 .It Dv AI_ADDRCONFIG
 128 If the
 129 .Dv AI_ADDRCONFIG
 130 bit is set, IPv4 addresses shall be returned only if
 131 an IPv4 address is configured on the local system,
 132 and IPv6 addresses shall be returned only if
 133 an IPv6 address is configured on the local system.
 134 .It Dv AI_ALL
 135 If the
 136 .Dv AI_ALL
 137 bit is set with the
 138 .Dv AI_V4MAPPED
 139 bit, then
 140 .Fn getaddrinfo
 141 shall return all matching IPv6 and IPv4 addresses.
 142 The
 143 .Dv AI_ALL
 144 bit without the
 145 .Dv AI_V4MAPPED
 146 bit is ignored.
 147 .It Dv AI_CANONNAME
 148 If the
 149 .Dv AI_CANONNAME
 150 bit is set, a successful call to
 151 .Fn getaddrinfo
 152 will return a NUL-terminated string containing the canonical name
 153 of the specified hostname in the
 154 .Fa ai_canonname
 155 element of the first
 156 .Li addrinfo
 157 structure returned.
 158 .It Dv AI_NUMERICHOST
 159 If the
 160 .Dv AI_NUMERICHOST
 161 bit is set, it indicates that
 162 .Fa hostname
 163 should be treated as a numeric string defining an IPv4 or IPv6 address
 164 and no name resolution should be attempted.
 165 .It Dv AI_NUMERICSERV
 166 If the
 167 .Dv AI_NUMERICSERV
 168 bit is set,
 169 then a non-null
 170 .Fa servname
 171 string supplied shall be a numeric port string.
 172 Otherwise, an
 173 .Dv EAI_NONAME
 174 error shall be returned.
 175 This bit shall prevent any type of name resolution service
 176 (for example, NIS+) from being invoked.
 177 .It Dv AI_PASSIVE
 178 If the
 179 .Dv AI_PASSIVE
 180 bit is set it indicates that the returned socket address structure
 181 is intended for use in a call to
 182 .Xr bind 2 .
 183 In this case, if the
 184 .Fa hostname
 185 argument is the null pointer, then the IP address portion of the
 186 socket address structure will be set to
 187 .Dv INADDR_ANY
 188 for an IPv4 address or
 189 .Dv IN6ADDR_ANY_INIT
 190 for an IPv6 address.
 191 .Pp
 192 If the
 193 .Dv AI_PASSIVE
 194 bit is not set, the returned socket address structure will be ready
 195 for use in a call to
 196 .Xr connect 2
 197 for a connection-oriented protocol or
 198 .Xr connect 2 ,
 199 .Xr sendto 2 ,
 200 or
 201 .Xr sendmsg 2
 202 if a connectionless protocol was chosen.
 203 The
 204 .Tn IP
 205 address portion of the socket address structure will be set to the
 206 loopback address if
 207 .Fa hostname
 208 is the null pointer and
 209 .Dv AI_PASSIVE
 210 is not set.
 211 .It Dv AI_V4MAPPED
 212 If the
 213 .Dv AI_V4MAPPED
 214 flag is specified along with an
 215 .Fa ai_family
 216 of
 217 .Dv AF_INET6 ,
 218 then
 219 .Fn getaddrinfo
 220 shall return IPv4-mapped IPv6 addresses
 221 on finding no matching IPv6 addresses (
 222 .Fa ai_addrlen
 223 shall be 16).
 224 The
 225 .Dv AI_V4MAPPED
 226 flag shall be ignored unless
 227 .Fa ai_family
 228 equals
 229 .Dv AF_INET6 .
 230 .El
 231 .El
 232 .Pp
 233 All other elements of the
 234 .Li addrinfo
 235 structure passed via
 236 .Fa hints
 237 must be zero or the null pointer.
 238 .Pp
 239 If
 240 .Fa hints
 241 is the null pointer,
 242 .Fn getaddrinfo
 243 behaves as if the caller provided a
 244 .Li struct addrinfo
 245 with
 246 .Fa ai_family
 247 set to
 248 .Dv PF_UNSPEC
 249 and all other elements set to zero or
 250 .Dv NULL .
 251 .Pp
 252 After a successful call to
 253 .Fn getaddrinfo ,
 254 .Fa *res
 255 is a pointer to a linked list of one or more
 256 .Li addrinfo
 257 structures.
 258 The list can be traversed by following the
 259 .Fa ai_next
 260 pointer in each
 261 .Li addrinfo
 262 structure until a null pointer is encountered.
 263 The three members
 264 .Fa ai_family ,
 265 .Fa ai_socktype ,
 266 and
 267 .Fa ai_protocol
 268 in each returned
 269 .Li addrinfo
 270 structure are suitable for a call to
 271 .Xr socket 2 .
 272 For each
 273 .Li addrinfo
 274 structure in the list, the
 275 .Fa ai_addr
 276 member points to a filled-in socket address structure of length
 277 .Fa ai_addrlen .
 278 .Pp
 279 This implementation of
 280 .Fn getaddrinfo
 281 allows numeric IPv6 address notation with scope identifier,
 282 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
 283 By appending the percent character and scope identifier to addresses,
 284 one can fill the
 285 .Li sin6_scope_id
 286 field for addresses.
 287 This would make management of scoped addresses easier
 288 and allows cut-and-paste input of scoped addresses.
 289 .Pp
 290 At this moment the code supports only link-local addresses with the format.
 291 The scope identifier is hardcoded to the name of the hardware interface
 292 associated
 293 with the link
 294 .Po
 295 such as
 296 .Li ne0
 297 .Pc .
 298 An example is
 299 .Dq Li fe80::1%ne0 ,
 300 which means
 301 .Do
 302 .Li fe80::1
 303 on the link associated with the
 304 .Li ne0
 305 interface
 306 .Dc .
 307 .Pp
 308 The current implementation assumes a one-to-one relationship between
 309 the interface and link, which is not necessarily true from the specification.
 310 .Pp
 311 All of the information returned by
 312 .Fn getaddrinfo
 313 is dynamically allocated: the
 314 .Li addrinfo
 315 structures themselves as well as the socket address structures and
 316 the canonical host name strings included in the
 317 .Li addrinfo
 318 structures.
 319 .Pp
 320 Memory allocated for the dynamically allocated structures created by
 321 a successful call to
 322 .Fn getaddrinfo
 323 is released by the
 324 .Fn freeaddrinfo
 325 function.
 326 The
 327 .Fa ai
 328 pointer should be a
 329 .Li addrinfo
 330 structure created by a call to
 331 .Fn getaddrinfo .
 332 .Sh RETURN VALUES
 333 .Fn getaddrinfo
 334 returns zero on success or one of the error codes listed in
 335 .Xr gai_strerror 3
 336 if an error occurs.
 337 .Sh EXAMPLES
 338 The following code tries to connect to
 339 .Dq Li www.kame.net
 340 service
 341 .Dq Li http
 342 via a stream socket.
 343 It loops through all the addresses available, regardless of address family.
 344 If the destination resolves to an IPv4 address, it will use an
 345 .Dv AF_INET
 346 socket.
 347 Similarly, if it resolves to IPv6, an
 348 .Dv AF_INET6
 349 socket is used.
 350 Observe that there is no hardcoded reference to a particular address family.
 351 The code works even if
 352 .Fn getaddrinfo
 353 returns addresses that are not IPv4/v6.
 354 .Bd -literal -offset indent
 355 struct addrinfo hints, *res, *res0;
 356 int error;
 357 int s;
 358 const char *cause = NULL;
 359
 360 memset(&hints, 0, sizeof(hints));
 361 hints.ai_family = PF_UNSPEC;
 362 hints.ai_socktype = SOCK_STREAM;
 363 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 364 if (error) {
 365         errx(1, "%s", gai_strerror(error));
 366         /*NOTREACHED*/
 367 }
 368 s = -1;
 369 for (res = res0; res; res = res->ai_next) {
 370         s = socket(res->ai_family, res->ai_socktype,
 371             res->ai_protocol);
 372         if (s < 0) {
 373                 cause = "socket";
 374                 continue;
 375         }
 376
 377         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 378                 cause = "connect";
 379                 close(s);
 380                 s = -1;
 381                 continue;
 382         }
 383
 384         break;  /* okay we got one */
 385 }
 386 if (s < 0) {
 387         err(1, "%s", cause);
 388         /*NOTREACHED*/
 389 }
 390 freeaddrinfo(res0);
 391 .Ed
 392 .Pp
 393 The following example tries to open a wildcard listening socket onto service
 394 .Dq Li http ,
 395 for all the address families available.
 396 .Bd -literal -offset indent
 397 struct addrinfo hints, *res, *res0;
 398 int error;
 399 int s[MAXSOCK];
 400 int nsock;
 401 const char *cause = NULL;
 402
 403 memset(&hints, 0, sizeof(hints));
 404 hints.ai_family = PF_UNSPEC;
 405 hints.ai_socktype = SOCK_STREAM;
 406 hints.ai_flags = AI_PASSIVE;
 407 error = getaddrinfo(NULL, "http", &hints, &res0);
 408 if (error) {
 409         errx(1, "%s", gai_strerror(error));
 410         /*NOTREACHED*/
 411 }
 412 nsock = 0;
 413 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 414         s[nsock] = socket(res->ai_family, res->ai_socktype,
 415             res->ai_protocol);
 416         if (s[nsock] < 0) {
 417                 cause = "socket";
 418                 continue;
 419         }
 420
 421         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 422                 cause = "bind";
 423                 close(s[nsock]);
 424                 continue;
 425         }
 426         (void) listen(s[nsock], 5);
 427
 428         nsock++;
 429 }
 430 if (nsock == 0) {
 431         err(1, "%s", cause);
 432         /*NOTREACHED*/
 433 }
 434 freeaddrinfo(res0);
 435 .Ed
 436 .Sh SEE ALSO
 437 .Xr bind 2 ,
 438 .Xr connect 2 ,
 439 .Xr send 2 ,
 440 .Xr socket 2 ,
 441 .Xr gai_strerror 3 ,
 442 .Xr gethostbyname 3 ,
 443 .Xr getnameinfo 3 ,
 444 .Xr getservbyname 3 ,
 445 .Xr resolver 3 ,
 446 .Xr hosts 5 ,
 447 .Xr resolv.conf 5 ,
 448 .Xr services 5 ,
 449 .Xr hostname 7 ,
 450 .Xr named 8
 451 .Rs
 452 .%A R. Gilligan
 453 .%A S. Thomson
 454 .%A J. Bound
 455 .%A J. McCann
 456 .%A W. Stevens
 457 .%T Basic Socket Interface Extensions for IPv6
 458 .%R RFC 3493
 459 .%D February 2003
 460 .Re
 461 .Rs
 462 .%A S. Deering
 463 .%A B. Haberman
 464 .%A T. Jinmei
 465 .%A E. Nordmark
 466 .%A B. Zill
 467 .%T "IPv6 Scoped Address Architecture"
 468 .%R internet draft
 469 .%N draft-ietf-ipv6-scoping-arch-02.txt
 470 .%O work in progress material
 471 .Re
 472 .Rs
 473 .%A Craig Metz
 474 .%T Protocol Independence Using the Sockets API
 475 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 476 .%D June 2000
 477 .Re
 478 .Sh STANDARDS
 479 The
 480 .Fn getaddrinfo
 481 function is defined by the
 482 .St -p1003.1g-2000
 483 draft specification and documented in
 484 .Dv "RFC 3493" ,
 485 .Dq Basic Socket Interface Extensions for IPv6 .
 486 .Sh BUGS
 487 The implementation of
 488 .Fn getaddrinfo
 489 is not thread-safe.