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