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