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 .\"     $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.29 2005/01/23 16:02:48 gnn Exp $
   4 .\"     $DragonFly: src/lib/libc/net/getaddrinfo.3,v 1.6 2007/08/18 20:48:47 swildner Exp $
   5 .\"
   6 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   7 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   8 .\"
   9 .\" Permission to use, copy, modify, and distribute this software for any
  10 .\" purpose with or without fee is hereby granted, provided that the above
  11 .\" copyright notice and this permission notice appear in all copies.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  14 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  15 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  16 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  17 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  18 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  19 .\" PERFORMANCE OF THIS SOFTWARE.
  20 .\"
  21 .Dd December 20, 2004
  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 LIBRARY
  29 .Lb libc
  30 .Sh SYNOPSIS
  31 .In sys/types.h
  32 .In sys/socket.h
  33 .In netdb.h
  34 .Ft int
  35 .Fn getaddrinfo "const char *hostname" "const char *servname" \
  36     "const struct addrinfo *hints" "struct addrinfo **res"
  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 .In 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 .Fa ai_flags
 123 is formed by
 124 .Tn OR Ns 'ing
 125 the following values:
 126 .Bl -tag -width "AI_CANONNAMEXX"
 127 .It Dv AI_CANONNAME
 128 If the
 129 .Dv AI_CANONNAME
 130 bit is set, a successful call to
 131 .Fn getaddrinfo
 132 will return a NUL-terminated string containing the canonical name
 133 of the specified hostname in the
 134 .Fa ai_canonname
 135 element of the first
 136 .Li addrinfo
 137 structure returned.
 138 .It Dv AI_NUMERICHOST
 139 If the
 140 .Dv AI_NUMERICHOST
 141 bit is set, it indicates that
 142 .Fa hostname
 143 should be treated as a numeric string defining an IPv4 or IPv6 address
 144 and no name resolution should be attempted.
 145 .It Dv AI_PASSIVE
 146 If the
 147 .Dv AI_PASSIVE
 148 bit is set it indicates that the returned socket address structure
 149 is intended for use in a call to
 150 .Xr bind 2 .
 151 In this case, if the
 152 .Fa hostname
 153 argument is the null pointer, then the IP address portion of the
 154 socket address structure will be set to
 155 .Dv INADDR_ANY
 156 for an IPv4 address or
 157 .Dv IN6ADDR_ANY_INIT
 158 for an IPv6 address.
 159 .Pp
 160 If the
 161 .Dv AI_PASSIVE
 162 bit is not set, the returned socket address structure will be ready
 163 for use in a call to
 164 .Xr connect 2
 165 for a connection-oriented protocol or
 166 .Xr connect 2 ,
 167 .Xr sendto 2 ,
 168 or
 169 .Xr sendmsg 2
 170 if a connectionless protocol was chosen.
 171 The
 172 .Tn IP
 173 address portion of the socket address structure will be set to the
 174 loopback address if
 175 .Fa hostname
 176 is the null pointer and
 177 .Dv AI_PASSIVE
 178 is not set.
 179 .El
 180 .El
 181 .Pp
 182 All other elements of the
 183 .Li addrinfo
 184 structure passed via
 185 .Fa hints
 186 must be zero or the null pointer.
 187 .Pp
 188 If
 189 .Fa hints
 190 is the null pointer,
 191 .Fn getaddrinfo
 192 behaves as if the caller provided a
 193 .Li struct addrinfo
 194 with
 195 .Fa ai_family
 196 set to
 197 .Dv PF_UNSPEC
 198 and all other elements set to zero or
 199 .Dv NULL .
 200 .Pp
 201 After a successful call to
 202 .Fn getaddrinfo ,
 203 .Fa *res
 204 is a pointer to a linked list of one or more
 205 .Li addrinfo
 206 structures.
 207 The list can be traversed by following the
 208 .Fa ai_next
 209 pointer in each
 210 .Li addrinfo
 211 structure until a null pointer is encountered.
 212 The three members
 213 .Fa ai_family ,
 214 .Fa ai_socktype ,
 215 and
 216 .Fa ai_protocol
 217 in each returned
 218 .Li addrinfo
 219 structure are suitable for a call to
 220 .Xr socket 2 .
 221 For each
 222 .Li addrinfo
 223 structure in the list, the
 224 .Fa ai_addr
 225 member points to a filled-in socket address structure of length
 226 .Fa ai_addrlen .
 227 .Pp
 228 This implementation of
 229 .Fn getaddrinfo
 230 allows numeric IPv6 address notation with scope identifier,
 231 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
 232 By appending the percent character and scope identifier to addresses,
 233 one can fill the
 234 .Li sin6_scope_id
 235 field for addresses.
 236 This would make management of scoped addresses easier
 237 and allows cut-and-paste input of scoped addresses.
 238 .Pp
 239 At this moment the code supports only link-local addresses with the format.
 240 The scope identifier is hardcoded to the name of the hardware interface
 241 associated
 242 with the link
 243 .Po
 244 such as
 245 .Li ne0
 246 .Pc .
 247 An example is
 248 .Dq Li fe80::1%ne0 ,
 249 which means
 250 .Do
 251 .Li fe80::1
 252 on the link associated with the
 253 .Li ne0
 254 interface
 255 .Dc .
 256 .Pp
 257 The current implementation assumes a one-to-one relationship between
 258 the interface and link, which is not necessarily true from the specification.
 259 .Pp
 260 All of the information returned by
 261 .Fn getaddrinfo
 262 is dynamically allocated: the
 263 .Li addrinfo
 264 structures themselves as well as the socket address structures and
 265 the canonical host name strings included in the
 266 .Li addrinfo
 267 structures.
 268 .Pp
 269 Memory allocated for the dynamically allocated structures created by
 270 a successful call to
 271 .Fn getaddrinfo
 272 is released by the
 273 .Fn freeaddrinfo
 274 function.
 275 The
 276 .Fa ai
 277 pointer should be a
 278 .Li addrinfo
 279 structure created by a call to
 280 .Fn getaddrinfo .
 281 .Sh RETURN VALUES
 282 .Fn getaddrinfo
 283 returns zero on success or one of the error codes listed in
 284 .Xr gai_strerror 3
 285 if an error occurs.
 286 .Sh EXAMPLES
 287 The following code tries to connect to
 288 .Dq Li www.kame.net
 289 service
 290 .Dq Li http
 291 via a stream socket.
 292 It loops through all the addresses available, regardless of address family.
 293 If the destination resolves to an IPv4 address, it will use an
 294 .Dv AF_INET
 295 socket.
 296 Similarly, if it resolves to IPv6, an
 297 .Dv AF_INET6
 298 socket is used.
 299 Observe that there is no hardcoded reference to a particular address family.
 300 The code works even if
 301 .Fn getaddrinfo
 302 returns addresses that are not IPv4/v6.
 303 .Bd -literal -offset indent
 304 struct addrinfo hints, *res, *res0;
 305 int error;
 306 int s;
 307 const char *cause = NULL;
 308
 309 memset(&hints, 0, sizeof(hints));
 310 hints.ai_family = PF_UNSPEC;
 311 hints.ai_socktype = SOCK_STREAM;
 312 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 313 if (error) {
 314         errx(1, "%s", gai_strerror(error));
 315         /*NOTREACHED*/
 316 }
 317 s = -1;
 318 for (res = res0; res; res = res->ai_next) {
 319         s = socket(res->ai_family, res->ai_socktype,
 320             res->ai_protocol);
 321         if (s < 0) {
 322                 cause = "socket";
 323                 continue;
 324         }
 325
 326         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 327                 cause = "connect";
 328                 close(s);
 329                 s = -1;
 330                 continue;
 331         }
 332
 333         break;  /* okay we got one */
 334 }
 335 if (s < 0) {
 336         err(1, "%s", cause);
 337         /*NOTREACHED*/
 338 }
 339 freeaddrinfo(res0);
 340 .Ed
 341 .Pp
 342 The following example tries to open a wildcard listening socket onto service
 343 .Dq Li http ,
 344 for all the address families available.
 345 .Bd -literal -offset indent
 346 struct addrinfo hints, *res, *res0;
 347 int error;
 348 int s[MAXSOCK];
 349 int nsock;
 350 const char *cause = NULL;
 351
 352 memset(&hints, 0, sizeof(hints));
 353 hints.ai_family = PF_UNSPEC;
 354 hints.ai_socktype = SOCK_STREAM;
 355 hints.ai_flags = AI_PASSIVE;
 356 error = getaddrinfo(NULL, "http", &hints, &res0);
 357 if (error) {
 358         errx(1, "%s", gai_strerror(error));
 359         /*NOTREACHED*/
 360 }
 361 nsock = 0;
 362 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 363         s[nsock] = socket(res->ai_family, res->ai_socktype,
 364             res->ai_protocol);
 365         if (s[nsock] < 0) {
 366                 cause = "socket";
 367                 continue;
 368         }
 369
 370         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 371                 cause = "bind";
 372                 close(s[nsock]);
 373                 continue;
 374         }
 375         (void) listen(s[nsock], 5);
 376
 377         nsock++;
 378 }
 379 if (nsock == 0) {
 380         err(1, "%s", cause);
 381         /*NOTREACHED*/
 382 }
 383 freeaddrinfo(res0);
 384 .Ed
 385 .Sh SEE ALSO
 386 .Xr bind 2 ,
 387 .Xr connect 2 ,
 388 .Xr send 2 ,
 389 .Xr socket 2 ,
 390 .Xr gai_strerror 3 ,
 391 .Xr gethostbyname 3 ,
 392 .Xr getnameinfo 3 ,
 393 .Xr getservbyname 3 ,
 394 .Xr resolver 3 ,
 395 .Xr hosts 5 ,
 396 .Xr resolv.conf 5 ,
 397 .Xr services 5 ,
 398 .Xr hostname 7 ,
 399 .Xr named 8
 400 .Rs
 401 .%A R. Gilligan
 402 .%A S. Thomson
 403 .%A J. Bound
 404 .%A J. McCann
 405 .%A W. Stevens
 406 .%T Basic Socket Interface Extensions for IPv6
 407 .%R RFC 3493
 408 .%D February 2003
 409 .Re
 410 .Rs
 411 .%A S. Deering
 412 .%A B. Haberman
 413 .%A T. Jinmei
 414 .%A E. Nordmark
 415 .%A B. Zill
 416 .%T "IPv6 Scoped Address Architecture"
 417 .%R internet draft
 418 .%N draft-ietf-ipv6-scoping-arch-02.txt
 419 .%O work in progress material
 420 .Re
 421 .Rs
 422 .%A Craig Metz
 423 .%T Protocol Independence Using the Sockets API
 424 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 425 .%D June 2000
 426 .Re
 427 .Sh STANDARDS
 428 The
 429 .Fn getaddrinfo
 430 function is defined by the
 431 .St -p1003.1g-2000
 432 draft specification and documented in
 433 .Dv "RFC 3493" ,
 434 .Dq Basic Socket Interface Extensions for IPv6 .
 435 .Sh BUGS
 436 The implementation of
 437 .Fn getaddrinfo
 438 is not thread-safe.