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