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 February 10, 2019
  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;       /* AI_PASSIVE, AI_CANONNAME, .. */
  82         int     ai_family;      /* AF_xxx */
  83         int     ai_socktype;    /* SOCK_xxx */
  84         int     ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  85         socklen_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 .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 IMPLEMENTATION NOTES
 355 The behavior of
 356 .Li freeadrinfo(NULL)
 357 is left unspecified by both
 358 .St -susv4
 359 and
 360 .Dv "RFC 3493" .
 361 The current implementation ignores a
 362 .Dv NULL
 363 argument for compatibility with programs that rely on the implementation
 364 details of other operating systems.
 365 .Sh RETURN VALUES
 366 .Fn getaddrinfo
 367 returns zero on success or one of the error codes listed in
 368 .Xr gai_strerror 3
 369 if an error occurs.
 370 .Sh EXAMPLES
 371 The following code tries to connect to
 372 .Dq Li www.kame.net
 373 service
 374 .Dq Li http
 375 via a stream socket.
 376 It loops through all the addresses available, regardless of address family.
 377 If the destination resolves to an IPv4 address, it will use an
 378 .Dv AF_INET
 379 socket.
 380 Similarly, if it resolves to IPv6, an
 381 .Dv AF_INET6
 382 socket is used.
 383 Observe that there is no hardcoded reference to a particular address family.
 384 The code works even if
 385 .Fn getaddrinfo
 386 returns addresses that are not IPv4/v6.
 387 .Bd -literal -offset indent
 388 struct addrinfo hints, *res, *res0;
 389 int error;
 390 int s;
 391 const char *cause = NULL;
 392
 393 memset(&hints, 0, sizeof(hints));
 394 hints.ai_family = AF_UNSPEC;
 395 hints.ai_socktype = SOCK_STREAM;
 396 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 397 if (error) {
 398         errx(1, "%s", gai_strerror(error));
 399         /* NOTREACHED */
 400 }
 401 s = -1;
 402 for (res = res0; res; res = res->ai_next) {
 403         s = socket(res->ai_family, res->ai_socktype,
 404             res->ai_protocol);
 405         if (s < 0) {
 406                 cause = "socket";
 407                 continue;
 408         }
 409
 410         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 411                 cause = "connect";
 412                 close(s);
 413                 s = -1;
 414                 continue;
 415         }
 416
 417         break;  /* okay we got one */
 418 }
 419 if (s < 0) {
 420         err(1, "%s", cause);
 421         /* NOTREACHED */
 422 }
 423 freeaddrinfo(res0);
 424 .Ed
 425 .Pp
 426 The following example tries to open a wildcard listening socket onto service
 427 .Dq Li http ,
 428 for all the address families available.
 429 .Bd -literal -offset indent
 430 struct addrinfo hints, *res, *res0;
 431 int error;
 432 int s[MAXSOCK];
 433 int nsock;
 434 const char *cause = NULL;
 435
 436 memset(&hints, 0, sizeof(hints));
 437 hints.ai_family = AF_UNSPEC;
 438 hints.ai_socktype = SOCK_STREAM;
 439 hints.ai_flags = AI_PASSIVE;
 440 error = getaddrinfo(NULL, "http", &hints, &res0);
 441 if (error) {
 442         errx(1, "%s", gai_strerror(error));
 443         /* NOTREACHED */
 444 }
 445 nsock = 0;
 446 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 447         s[nsock] = socket(res->ai_family, res->ai_socktype,
 448             res->ai_protocol);
 449         if (s[nsock] < 0) {
 450                 cause = "socket";
 451                 continue;
 452         }
 453
 454         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 455                 cause = "bind";
 456                 close(s[nsock]);
 457                 continue;
 458         }
 459         (void) listen(s[nsock], 5);
 460
 461         nsock++;
 462 }
 463 if (nsock == 0) {
 464         err(1, "%s", cause);
 465         /* NOTREACHED */
 466 }
 467 freeaddrinfo(res0);
 468 .Ed
 469 .Sh SEE ALSO
 470 .Xr bind 2 ,
 471 .Xr connect 2 ,
 472 .Xr send 2 ,
 473 .Xr socket 2 ,
 474 .Xr gai_strerror 3 ,
 475 .Xr gethostbyname 3 ,
 476 .Xr getnameinfo 3 ,
 477 .Xr getservbyname 3 ,
 478 .Xr resolver 3 ,
 479 .Xr inet 4 ,
 480 .Xr inet6 4 ,
 481 .Xr unix 4 ,
 482 .Xr hosts 5 ,
 483 .Xr resolv.conf 5 ,
 484 .Xr services 5 ,
 485 .Xr hostname 7 ,
 486 .Xr named 8
 487 .Rs
 488 .%A R. Gilligan
 489 .%A S. Thomson
 490 .%A J. Bound
 491 .%A J. McCann
 492 .%A W. Stevens
 493 .%T Basic Socket Interface Extensions for IPv6
 494 .%R RFC 3493
 495 .%D February 2003
 496 .Re
 497 .Rs
 498 .%A S. Deering
 499 .%A B. Haberman
 500 .%A T. Jinmei
 501 .%A E. Nordmark
 502 .%A B. Zill
 503 .%T "IPv6 Scoped Address Architecture"
 504 .%R RFC 4007
 505 .%D March 2005
 506 .Re
 507 .Rs
 508 .%A Craig Metz
 509 .%T Protocol Independence Using the Sockets API
 510 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 511 .%D June 2000
 512 .Re
 513 .Sh STANDARDS
 514 The
 515 .Fn getaddrinfo
 516 function is defined by the
 517 .St -p1003.1-2004
 518 specification and documented in
 519 .Dv "RFC 3493" ,
 520 .Dq Basic Socket Interface Extensions for IPv6 .