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