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