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 19, 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 .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 flag is used with the
 148 .Dv AI_V4MAPPED
 149 flag, then
 150 .Fn getaddrinfo
 151 shall return all matching IPv6 and IPv4 addresses.
 152 .Pp
 153 For example, when using the DNS, queries are made for both AAAA records and A records, and
 154 .Fn getaddrinfo
 155 returns the combined results of both queries.
 156 Any IPv4 addresses found are returned as IPv4-mapped IPv6 addresses.
 157 .Pp
 158 The
 159 .Dv AI_ALL
 160 flag without the
 161 .Dv AI_V4MAPPED
 162 flag is ignored.
 163 .It Dv AI_CANONNAME
 164 If the
 165 .Dv AI_CANONNAME
 166 bit is set, a successful call to
 167 .Fn getaddrinfo
 168 will return a NUL-terminated string containing the canonical name
 169 of the specified hostname in the
 170 .Fa ai_canonname
 171 element of the first
 172 .Li addrinfo
 173 structure returned.
 174 .It Dv AI_NUMERICHOST
 175 If the
 176 .Dv AI_NUMERICHOST
 177 bit is set, it indicates that
 178 .Fa hostname
 179 should be treated as a numeric string defining an IPv4 or IPv6 address
 180 and no name resolution should be attempted.
 181 .It Dv AI_NUMERICSERV
 182 If the
 183 .Dv AI_NUMERICSERV
 184 bit is set,
 185 then a non-null
 186 .Fa servname
 187 string supplied shall be a numeric port string.
 188 Otherwise, an
 189 .Dv EAI_NONAME
 190 error shall be returned.
 191 This bit shall prevent any type of name resolution service
 192 (for example, NIS+) from being invoked.
 193 .It Dv AI_PASSIVE
 194 If the
 195 .Dv AI_PASSIVE
 196 bit is set it indicates that the returned socket address structure
 197 is intended for use in a call to
 198 .Xr bind 2 .
 199 In this case, if the
 200 .Fa hostname
 201 argument is the null pointer, then the IP address portion of the
 202 socket address structure will be set to
 203 .Dv INADDR_ANY
 204 for an IPv4 address or
 205 .Dv IN6ADDR_ANY_INIT
 206 for an IPv6 address.
 207 .Pp
 208 If the
 209 .Dv AI_PASSIVE
 210 bit is not set, the returned socket address structure will be ready
 211 for use in a call to
 212 .Xr connect 2
 213 for a connection-oriented protocol or
 214 .Xr connect 2 ,
 215 .Xr sendto 2 ,
 216 or
 217 .Xr sendmsg 2
 218 if a connectionless protocol was chosen.
 219 The
 220 .Tn IP
 221 address portion of the socket address structure will be set to the
 222 loopback address if
 223 .Fa hostname
 224 is the null pointer and
 225 .Dv AI_PASSIVE
 226 is not set.
 227 .It Dv AI_V4MAPPED
 228 If the
 229 .Dv AI_V4MAPPED
 230 flag is specified along with an ai_family of
 231 .Dv AF_INET6 ,
 232 then
 233 .Fn getaddrinfo
 234 shall return IPv4-mapped IPv6 addresses on finding no matching IPv6 addresses (
 235 .Fa ai_addrlen
 236 shall be 16).
 237 .Pp
 238 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.
 239 .Pp
 240 The
 241 .Dv AI_V4MAPPED
 242 flag shall be ignored unless
 243 .Fa ai_family
 244 equals
 245 .Dv AF_INET6 .
 246 .El
 247 .El
 248 .Pp
 249 All other elements of the
 250 .Li addrinfo
 251 structure passed via
 252 .Fa hints
 253 must be zero or the null pointer.
 254 .Pp
 255 If
 256 .Fa hints
 257 is the null pointer,
 258 .Fn getaddrinfo
 259 behaves as if the caller provided a
 260 .Li struct addrinfo
 261 with
 262 .Fa ai_family
 263 set to
 264 .Dv PF_UNSPEC
 265 and all other elements set to zero or
 266 .Dv NULL .
 267 .Pp
 268 After a successful call to
 269 .Fn getaddrinfo ,
 270 .Fa *res
 271 is a pointer to a linked list of one or more
 272 .Li addrinfo
 273 structures.
 274 The list can be traversed by following the
 275 .Fa ai_next
 276 pointer in each
 277 .Li addrinfo
 278 structure until a null pointer is encountered.
 279 The three members
 280 .Fa ai_family,
 281 .Fa ai_socktype,
 282 and
 283 .Fa ai_protocol
 284 in each returned
 285 .Li addrinfo
 286 structure are suitable for a call to
 287 .Xr socket 2 .
 288 For each
 289 .Li addrinfo
 290 structure in the list, the
 291 .Fa ai_addr
 292 member points to a filled-in socket address structure of length
 293 .Fa ai_addrlen .
 294 .Pp
 295 This implementation of
 296 .Fn getaddrinfo
 297 allows numeric IPv6 address notation with scope identifier,
 298 as documented in chapter 11 of RFC 4007.
 299 By appending the percent character and scope identifier to addresses,
 300 one can fill the
 301 .Li sin6_scope_id
 302 field for addresses.
 303 This would make management of scoped addresses easier
 304 and allows cut-and-paste input of scoped addresses.
 305 .Pp
 306 At this moment the code supports only link-local addresses with the format.
 307 The scope identifier is hardcoded to the name of the hardware interface
 308 associated
 309 with the link
 310 .Po
 311 such as
 312 .Li ne0
 313 .Pc .
 314 An example is
 315 .Dq Li fe80::1%ne0 ,
 316 which means
 317 .Do
 318 .Li fe80::1
 319 on the link associated with the
 320 .Li ne0
 321 interface
 322 .Dc .
 323 .Pp
 324 The current implementation assumes a one-to-one relationship between
 325 the interface and link, which is not necessarily true from the specification.
 326 .Pp
 327 All of the information returned by
 328 .Fn getaddrinfo
 329 is dynamically allocated: the
 330 .Li addrinfo
 331 structures themselves as well as the socket address structures and
 332 the canonical host name strings included in the
 333 .Li addrinfo
 334 structures.
 335 .Pp
 336 Memory allocated for the dynamically allocated structures created by
 337 a successful call to
 338 .Fn getaddrinfo
 339 is released by the
 340 .Fn freeaddrinfo
 341 function.
 342 The
 343 .Fa ai
 344 pointer should be a
 345 .Li addrinfo
 346 structure created by a call to
 347 .Fn getaddrinfo .
 348 .Sh RETURN VALUES
 349 .Fn getaddrinfo
 350 returns zero on success or one of the error codes listed in
 351 .Xr gai_strerror 3
 352 if an error occurs.
 353 .Sh EXAMPLES
 354 The following code tries to connect to
 355 .Dq Li www.kame.net
 356 service
 357 .Dq Li http
 358 via a stream socket.
 359 It loops through all the addresses available, regardless of address family.
 360 If the destination resolves to an IPv4 address, it will use an
 361 .Dv AF_INET
 362 socket.
 363 Similarly, if it resolves to IPv6, an
 364 .Dv AF_INET6
 365 socket is used.
 366 Observe that there is no hardcoded reference to a particular address family.
 367 The code works even if
 368 .Fn getaddrinfo
 369 returns addresses that are not IPv4/v6.
 370 .Bd -literal -offset indent
 371 struct addrinfo hints, *res, *res0;
 372 int error;
 373 int s;
 374 const char *cause = NULL;
 375
 376 memset(&hints, 0, sizeof(hints));
 377 hints.ai_family = PF_UNSPEC;
 378 hints.ai_socktype = SOCK_STREAM;
 379 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 380 if (error) {
 381         errx(1, "%s", gai_strerror(error));
 382         /* NOTREACHED */
 383 }
 384 s = -1;
 385 for (res = res0; res; res = res->ai_next) {
 386         s = socket(res->ai_family, res->ai_socktype,
 387             res->ai_protocol);
 388         if (s < 0) {
 389                 cause = "socket";
 390                 continue;
 391         }
 392
 393         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 394                 cause = "connect";
 395                 close(s);
 396                 s = -1;
 397                 continue;
 398         }
 399
 400         break;  /* okay we got one */
 401 }
 402 if (s < 0) {
 403         err(1, "%s", cause);
 404         /* NOTREACHED */
 405 }
 406 freeaddrinfo(res0);
 407 .Ed
 408 .Pp
 409 The following example tries to open a wildcard listening socket onto service
 410 .Dq Li http ,
 411 for all the address families available.
 412 .Bd -literal -offset indent
 413 struct addrinfo hints, *res, *res0;
 414 int error;
 415 int s[MAXSOCK];
 416 int nsock;
 417 const char *cause = NULL;
 418
 419 memset(&hints, 0, sizeof(hints));
 420 hints.ai_family = PF_UNSPEC;
 421 hints.ai_socktype = SOCK_STREAM;
 422 hints.ai_flags = AI_PASSIVE;
 423 error = getaddrinfo(NULL, "http", &hints, &res0);
 424 if (error) {
 425         errx(1, "%s", gai_strerror(error));
 426         /* NOTREACHED */
 427 }
 428 nsock = 0;
 429 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 430         s[nsock] = socket(res->ai_family, res->ai_socktype,
 431             res->ai_protocol);
 432         if (s[nsock] < 0) {
 433                 cause = "socket";
 434                 continue;
 435         }
 436
 437         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 438                 cause = "bind";
 439                 close(s[nsock]);
 440                 continue;
 441         }
 442         (void) listen(s[nsock], 5);
 443
 444         nsock++;
 445 }
 446 if (nsock == 0) {
 447         err(1, "%s", cause);
 448         /* NOTREACHED */
 449 }
 450 freeaddrinfo(res0);
 451 .Ed
 452 .Sh SEE ALSO
 453 .Xr bind 2 ,
 454 .Xr connect 2 ,
 455 .Xr send 2 ,
 456 .Xr socket 2 ,
 457 .Xr gai_strerror 3 ,
 458 .Xr gethostbyname 3 ,
 459 .Xr getnameinfo 3 ,
 460 .Xr getservbyname 3 ,
 461 .Xr resolver 3 ,
 462 .Xr hosts 5 ,
 463 .Xr resolv.conf 5 ,
 464 .Xr services 5 ,
 465 .Xr hostname 7 ,
 466 .Xr named 8
 467 .Rs
 468 .%A R. Gilligan
 469 .%A S. Thomson
 470 .%A J. Bound
 471 .%A J. McCann
 472 .%A W. Stevens
 473 .%T Basic Socket Interface Extensions for IPv6
 474 .%R RFC 3493
 475 .%D February 2003
 476 .Re
 477 .Rs
 478 .%A S. Deering
 479 .%A B. Haberman
 480 .%A T. Jinmei
 481 .%A E. Nordmark
 482 .%A B. Zill
 483 .%T "IPv6 Scoped Address Architecture"
 484 .%R RFC 4007
 485 .%D March 2005
 486 .Re
 487 .Rs
 488 .%A Craig Metz
 489 .%T Protocol Independence Using the Sockets API
 490 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 491 .%D June 2000
 492 .Re
 493 .Sh STANDARDS
 494 The
 495 .Fn getaddrinfo
 496 function is defined by the
 497 .St -p1003.1-2004
 498 specification and documented in
 499 .Dv "RFC 3493" ,
 500 .Dq Basic Socket Interface Extensions for IPv6 .