original/man3/getaddrinfo.3

   1 .\" Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (c) 2006 Ulrich Drepper <drepper@redhat.com>
   3 .\" A few pieces of an earlier version remain:
   4 .\" Copyright 2000, Sam Varshavchik <mrsam@courier-mta.com>
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .\" References: RFC 2553
  27 .\"
  28 .\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED,
  29 .\"                     and AI_NUMERICSERV.
  30 .\" 2006-11-25, Ulrich Drepper <drepper@redhat.com>
  31 .\"     Add text describing Internationalized Domain Name extensions.
  32 .\" 2007-06-08, mtk: added example programs
  33 .\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other
  34 .\"     minor rewrites.
  35 .\" 2008-06-18, mtk: many parts rewritten
  36 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>
  37 .\"     Describe results ordering and reference /etc/gai.conf.
  38 .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support
  39 .\"           and is SCTP support now also there?
  40 .\"
  41 .TH GETADDRINFO 3 2010-09-27 "GNU" "Linux Programmer's Manual"
  42 .SH NAME
  43 getaddrinfo, freeaddrinfo, gai_strerror \- network address and
  44 service translation
  45 .SH SYNOPSIS
  46 .nf
  47 .B #include <sys/types.h>
  48 .B #include <sys/socket.h>
  49 .B #include <netdb.h>
  50 .sp
  51 .BI "int getaddrinfo(const char *" "node" ", const char *" "service" ,
  52 .BI "                const struct addrinfo *" "hints" ,
  53 .BI "                struct addrinfo **" "res" );
  54 .sp
  55 .BI "void freeaddrinfo(struct addrinfo *" "res" );
  56 .sp
  57 .BI "const char *gai_strerror(int " "errcode" );
  58 .fi
  59 .sp
  60 .in -4n
  61 Feature Test Macro Requirements for glibc (see
  62 .BR feature_test_macros (7)):
  63 .ad l
  64 .in
  65 .sp
  66 .BR getaddrinfo (),
  67 .BR freeaddrinfo (),
  68 .BR gai_strerror ():
  69 .RS 4
  70 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
  71 .RE
  72 .ad b
  73 .SH DESCRIPTION
  74 Given
  75 .I node
  76 and
  77 .IR service ,
  78 which identify an Internet host and a service,
  79 .BR getaddrinfo ()
  80 returns one or more
  81 .I addrinfo
  82 structures, each of which contains an Internet address
  83 that can be specified in a call to
  84 .BR bind (2)
  85 or
  86 .BR connect (2).
  87 The
  88 .BR getaddrinfo ()
  89 function combines the functionality provided by the
  90 .\" .BR getipnodebyname (3),
  91 .\" .BR getipnodebyaddr (3),
  92 .BR getservbyname (3)
  93 and
  94 .BR getservbyport (3)
  95 functions into a single interface, but unlike the latter functions,
  96 .BR getaddrinfo ()
  97 is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies.
  98 .PP
  99 The
 100 .I addrinfo
 101 structure used by
 102 .BR getaddrinfo ()
 103 contains the following fields:
 104 .sp
 105 .in +4n
 106 .nf
 107 struct addrinfo {
 108     int              ai_flags;
 109     int              ai_family;
 110     int              ai_socktype;
 111     int              ai_protocol;
 112     size_t           ai_addrlen;
 113     struct sockaddr *ai_addr;
 114     char            *ai_canonname;
 115     struct addrinfo *ai_next;
 116 };
 117 .fi
 118 .in
 119 .PP
 120 The
 121 .I hints
 122 argument points to an
 123 .I addrinfo
 124 structure that specifies criteria for selecting the socket address
 125 structures returned in the list pointed to by
 126 .IR res .
 127 If
 128 .I hints
 129 is not NULL it points to an
 130 .I addrinfo
 131 structure whose
 132 .IR ai_family ,
 133 .IR ai_socktype ,
 134 and
 135 .I ai_protocol
 136 specify criteria that limit the set of socket addresses returned by
 137 .BR getaddrinfo (),
 138 as follows:
 139 .TP 12
 140 .I ai_family
 141 This field specifies the desired address family for the returned addresses.
 142 Valid values for this field include
 143 .BR AF_INET
 144 and
 145 .BR AF_INET6 .
 146 The value
 147 .B AF_UNSPEC
 148 indicates that
 149 .BR getaddrinfo ()
 150 should return socket addresses for any address family
 151 (either IPv4 or IPv6, for example) that can be used with
 152 .I node
 153 and
 154 .IR service .
 155 .TP
 156 .I ai_socktype
 157 This field specifies the preferred socket type, for example
 158 .BR SOCK_STREAM
 159 or
 160 .BR SOCK_DGRAM .
 161 Specifying 0 in this field indicates that socket addresses of any type
 162 can be returned by
 163 .BR getaddrinfo ().
 164 .TP
 165 .I ai_protocol
 166 This field specifies the protocol for the returned socket addresses.
 167 Specifying 0 in this field indicates that socket addresses with
 168 any protocol can be returned by
 169 .BR getaddrinfo ().
 170 .TP
 171 .I ai_flags
 172 This field specifies additional options, described below.
 173 Multiple flags are specified by bitwise OR-ing them together.
 174 .PP
 175 All the other fields in the structure pointed to by
 176 .I hints
 177 must contain either 0 or a NULL pointer, as appropriate.
 178 Specifying
 179 .I hints
 180 as NULL is equivalent to setting
 181 .I ai_socktype
 182 and
 183 .I ai_protocol
 184 to 0;
 185 .I ai_family
 186 to
 187 .BR AF_UNSPEC ;
 188 and
 189 .I ai_flags
 190 to
 191 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" .
 192
 193 .I node
 194 specifies either a numerical network address
 195 (for IPv4, numbers-and-dots notation as supported by
 196 .BR inet_aton (3);
 197 for IPv6, hexadecimal string format as supported by
 198 .BR inet_pton (3)),
 199 or a network hostname, whose network addresses are looked up and resolved.
 200 If
 201 .I hints.ai_flags
 202 contains the
 203 .B AI_NUMERICHOST
 204 flag then
 205 .I node
 206 must be a numerical network address.
 207 The
 208 .B AI_NUMERICHOST
 209 flag suppresses any potentially lengthy network host address lookups.
 210 .PP
 211 If the
 212 .B AI_PASSIVE
 213 flag is specified in
 214 .IR hints.ai_flags ,
 215 and
 216 .I node
 217 is NULL,
 218 then the returned socket addresses will be suitable for
 219 .BR bind (2)ing
 220 a socket that will
 221 .BR accept (2)
 222 connections.
 223 The returned socket address will contain the "wildcard address"
 224 .RB ( INADDR_ANY
 225 for IPv4 addresses,
 226 .BR IN6ADDR_ANY_INIT
 227 for IPv6 address).
 228 The wildcard address is used by applications (typically servers)
 229 that intend to accept connections on any of the hosts's network addresses.
 230 If
 231 .I node
 232 is not NULL, then the
 233 .B AI_PASSIVE
 234 flag is ignored.
 235 .PP
 236 If the
 237 .B AI_PASSIVE
 238 flag is not set in
 239 .IR hints.ai_flags ,
 240 then the returned socket addresses will be suitable for use with
 241 .BR connect (2),
 242 .BR sendto (2),
 243 or
 244 .BR sendmsg (2).
 245 If
 246 .I node
 247 is NULL,
 248 then the network address will be set to the loopback interface address
 249 .RB ( INADDR_LOOPBACK
 250 for IPv4 addresses,
 251 .BR IN6ADDR_LOOPBACK_INIT
 252 for IPv6 address);
 253 this is used by applications that intend to communicate
 254 with peers running on the same host.
 255 .PP
 256 .I service
 257 sets the port in each returned address structure.
 258 If this argument is a service name (see
 259 .BR services (5)),
 260 it is translated to the corresponding port number.
 261 This argument can also be specified as a decimal number,
 262 which is simply converted to binary.
 263 If
 264 .I service
 265 is NULL, then the port number of the returned socket addresses
 266 will be left uninitialized.
 267 If
 268 .B AI_NUMERICSERV
 269 is specified in
 270 .I hints.ai_flags
 271 and
 272 .I service
 273 is not NULL, then
 274 .I service
 275 must point to a string containing a numeric port number.
 276 This flag is used to inhibit the invocation of a name resolution service
 277 in cases where it is known not to be required.
 278 .PP
 279 Either
 280 .I node
 281 or
 282 .IR service ,
 283 but not both, may be NULL.
 284 .PP
 285 The
 286 .BR getaddrinfo ()
 287 function allocates and initializes a linked list of
 288 .I addrinfo
 289 structures, one for each network address that matches
 290 .I node
 291 and
 292 .IR service ,
 293 subject to any restrictions imposed by
 294 .IR hints ,
 295 and returns a pointer to the start of the list in
 296 .IR res .
 297 The items in the linked list are linked by the
 298 .I ai_next
 299 field.
 300
 301 There are several reasons why
 302 the linked list may have more than one
 303 .I addrinfo
 304 structure, including: the network host is multihomed, accessible
 305 over multiple protocols (e.g. both
 306 .BR AF_INET
 307 and
 308 .BR AF_INET6 );
 309 or the same service is available from multiple socket types (one
 310 .B SOCK_STREAM
 311 address and another
 312 .B SOCK_DGRAM
 313 address, for example).
 314 Normally, the application should try
 315 using the addresses in the order in which they are returned.
 316 The sorting function used within
 317 .BR getaddrinfo ()
 318 is defined in RFC\ 3484; the order can be tweaked for a particular
 319 system by editing
 320 .IR /etc/gai.conf
 321 (available since glibc 2.5).
 322 .PP
 323 If
 324 .I hints.ai_flags
 325 includes the
 326 .B AI_CANONNAME
 327 flag, then the
 328 .I ai_canonname
 329 field of the first of the
 330 .I addrinfo
 331 structures in the returned list is set to point to the
 332 official name of the host.
 333 .\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo
 334 .\" structure was set pointing to the canonical name; that was
 335 .\" more than POSIX.1-2001 specified, or other implementations provided.
 336 .\" MTK, Aug 05
 337
 338 The remaining fields of each returned
 339 .I addrinfo
 340 structure are initialized as follows:
 341 .IP * 2
 342 The
 343 .IR ai_family ,
 344 .IR ai_socktype ,
 345 and
 346 .I ai_protocol
 347 fields return the socket creation parameters (i.e., these fields have
 348 the same meaning as the corresponding arguments of
 349 .BR socket (2)).
 350 For example,
 351 .I ai_family
 352 might return
 353 .B AF_INET
 354 or
 355 .BR AF_INET6 ;
 356 .I ai_socktype
 357 might return
 358 .B SOCK_DGRAM
 359 or
 360 .BR SOCK_STREAM ;
 361 and
 362 .I ai_protocol
 363 returns the protocol for the socket.
 364 .IP *
 365 A pointer to the socket address is placed in the
 366 .I ai_addr
 367 field, and the length of the socket address, in bytes,
 368 is placed in the
 369 .I ai_addrlen
 370 field.
 371 .PP
 372 If
 373 .I hints.ai_flags
 374 includes the
 375 .B AI_ADDRCONFIG
 376 flag, then IPv4 addresses are returned in the list pointed to by
 377 .I res
 378 only if the local system has at least one
 379 IPv4 address configured, and IPv6 addresses are only returned
 380 if the local system has at least one IPv6 address configured.
 381 .PP
 382 If
 383 .I hint.ai_flags
 384 specifies the
 385 .B AI_V4MAPPED
 386 flag, and
 387 .I hints.ai_family
 388 was specified as
 389 .BR AF_INET6 ,
 390 and no matching IPv6 addresses could be found,
 391 then return IPv4-mapped IPv6 addresses in the list pointed to by
 392 .IR res .
 393 If both
 394 .B AI_V4MAPPED
 395 and
 396 .B AI_ALL
 397 are specified in
 398 .IR hints.ai_flags ,
 399 then return both IPv6 and IPv4-mapped IPv6 addresses
 400 in the list pointed to by
 401 .IR res .
 402 .B AI_ALL
 403 is ignored if
 404 .B AI_V4MAPPED
 405 is not also specified.
 406 .PP
 407 The
 408 .BR freeaddrinfo ()
 409 function frees the memory that was allocated
 410 for the dynamically allocated linked list
 411 .IR res .
 412 .SS "Extensions to getaddrinfo() for Internationalized Domain Names"
 413 .PP
 414 Starting with glibc 2.3.4,
 415 .BR getaddrinfo ()
 416 has been extended to selectively allow the incoming and outgoing
 417 hostnames to be transparently converted to and from the
 418 Internationalized Domain Name (IDN) format (see RFC 3490,
 419 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
 420 Four new flags are defined:
 421 .TP
 422 .B AI_IDN
 423 If this flag is specified, then the node name given in
 424 .I node
 425 is converted to IDN format if necessary.
 426 The source encoding is that of the current locale.
 427
 428 If the input name contains non-ASCII characters, then the IDN encoding
 429 is used.
 430 Those parts of the node name (delimited by dots) that contain
 431 non-ASCII characters are encoded using ASCII Compatible Encoding (ACE)
 432 before being passed to the name resolution functions.
 433 .\" Implementation Detail:
 434 .\" To minimize effects on system performance the implementation might
 435 .\" want to check whether the input string contains any non-ASCII
 436 .\" characters.  If there are none the IDN step can be skipped completely.
 437 .\" On systems which allow not-ASCII safe encodings for a locale this
 438 .\" might be a problem.
 439 .TP
 440 .B AI_CANONIDN
 441 After a successful name lookup, and if the
 442 .B AI_CANONNAME
 443 flag was specified,
 444 .BR getaddrinfo ()
 445 will return the canonical name of the
 446 node corresponding to the
 447 .I addrinfo
 448 structure value passed back.
 449 The return value is an exact copy of the value returned by the name
 450 resolution function.
 451
 452 If the name is encoded using ACE, then it will contain the
 453 .I xn\-\-
 454 prefix for one or more components of the name.
 455 To convert these components into a readable form the
 456 .B AI_CANONIDN
 457 flag can be passed in addition to
 458 .BR AI_CANONNAME .
 459 The resulting string is encoded using the current locale's encoding.
 460 .\"
 461 .\"Implementation Detail:
 462 .\"If no component of the returned name starts with xn\-\- the IDN
 463 .\"step can be skipped, therefore avoiding unnecessary slowdowns.
 464 .TP
 465 .BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES
 466 Setting these flags will enable the
 467 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
 468 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
 469 conforming hostname)
 470 flags respectively to be used in the IDNA handling.
 471 .SH "RETURN VALUE"
 472 .\" FIXME glibc defines the following additional errors, some which
 473 .\" can probably be returned by getaddrinfo(); they need to
 474 .\" be documented.
 475 .\" #ifdef __USE_GNU
 476 .\" #define EAI_INPROGRESS  -100  /* Processing request in progress.  */
 477 .\" #define EAI_CANCELED    -101  /* Request canceled.  */
 478 .\" #define EAI_NOTCANCELED -102  /* Request not canceled.  */
 479 .\" #define EAI_ALLDONE     -103  /* All requests done.  */
 480 .\" #define EAI_INTR        -104  /* Interrupted by a signal.  */
 481 .\" #define EAI_IDN_ENCODE  -105  /* IDN encoding failed.  */
 482 .\" #endif
 483 .BR getaddrinfo ()
 484 returns 0 if it succeeds, or one of the following nonzero error codes:
 485 .TP
 486 .B EAI_ADDRFAMILY
 487 .\" Not in SUSv3
 488 The specified network host does not have any network addresses in the
 489 requested address family.
 490 .TP
 491 .B EAI_AGAIN
 492 The name server returned a temporary failure indication.
 493 Try again later.
 494 .TP
 495 .B EAI_BADFLAGS
 496 .I hints.ai_flags
 497 contains invalid flags; or,
 498 .I hints.ai_flags
 499 included
 500 .B AI_CANONNAME
 501 and
 502 .I name
 503 was NULL.
 504 .TP
 505 .B EAI_FAIL
 506 The name server returned a permanent failure indication.
 507 .TP
 508 .B EAI_FAMILY
 509 The requested address family is not supported.
 510 .TP
 511 .B EAI_MEMORY
 512 Out of memory.
 513 .TP
 514 .B EAI_NODATA
 515 .\" Not in SUSv3
 516 The specified network host exists, but does not have any
 517 network addresses defined.
 518 .TP
 519 .B EAI_NONAME
 520 The
 521 .I node
 522 or
 523 .I service
 524 is not known; or both
 525 .I node
 526 and
 527 .I service
 528 are NULL; or
 529 .B AI_NUMERICSERV
 530 was specified in
 531 .I hints.ai_flags
 532 and
 533 .I service
 534 was not a numeric port-number string.
 535 .TP
 536 .B EAI_SERVICE
 537 The requested service is not available for the requested socket type.
 538 It may be available through another socket type.
 539 For example, this error could occur if
 540 .I service
 541 was "shell" (a service only available on stream sockets), and either
 542 .I hints.ai_protocol
 543 was
 544 .BR IPPROTO_UDP ,
 545 or
 546 .I hints.ai_socktype
 547 was
 548 .BR SOCK_DGRAM ;
 549 or the error could occur if
 550 .I service
 551 was not NULL, and
 552 .I hints.ai_socktype
 553 was
 554 .BR SOCK_RAW
 555 (a socket type that does not support the concept of services).
 556 .TP
 557 .B EAI_SOCKTYPE
 558 The requested socket type is not supported.
 559 This could occur, for example, if
 560 .I hints.ai_socktype
 561 and
 562 .I hints.ai_protocol
 563 are inconsistent (e.g.,
 564 .BR SOCK_DGRAM
 565 and
 566 .BR IPPROTO_TCP ,
 567 respectively).
 568 .TP
 569 .B EAI_SYSTEM
 570 Other system error, check
 571 .I errno
 572 for details.
 573 .PP
 574 The
 575 .BR gai_strerror ()
 576 function translates these error codes to a human readable string,
 577 suitable for error reporting.
 578 .SH "FILES"
 579 .I /etc/gai.conf
 580 .SH "CONFORMING TO"
 581 POSIX.1-2001.
 582 The
 583 .BR getaddrinfo ()
 584 function is documented in RFC\ 2553.
 585 .SH "NOTES"
 586 .BR getaddrinfo ()
 587 supports the
 588 .IB address % scope-id
 589 notation for specifying the IPv6 scope-ID.
 590
 591 .BR AI_ADDRCONFIG ,
 592 .BR AI_ALL ,
 593 and
 594 .B AI_V4MAPPED
 595 are available since glibc 2.3.3.
 596 .B AI_NUMERICSERV
 597 is available since glibc 2.3.4.
 598
 599 According to POSIX.1-2001, specifying
 600 .I hints
 601 as NULL should cause
 602 .I ai_flags
 603 to be assumed as 0.
 604 The GNU C library instead assumes a value of
 605 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)"
 606 for this case,
 607 since this value is considered an improvement on the specification.
 608 .SH EXAMPLE
 609 .\" getnameinfo.3 refers to this example
 610 .\" socket.2 refers to this example
 611 .\" bind.2 refers to this example
 612 .\" connect.2 refers to this example
 613 .\" recvfrom.2 refers to this example
 614 .\" sendto.2 refers to this example
 615 The following programs demonstrate the use of
 616 .BR getaddrinfo (),
 617 .BR gai_strerror (),
 618 .BR freeaddrinfo (),
 619 and
 620 .BR getnameinfo (3).
 621 The programs are an echo server and client for UDP datagrams.
 622 .SS Server program
 623 \&
 624 .nf
 625 #include <sys/types.h>
 626 #include <stdio.h>
 627 #include <stdlib.h>
 628 #include <unistd.h>
 629 #include <string.h>
 630 #include <sys/socket.h>
 631 #include <netdb.h>
 632
 633 #define BUF_SIZE 500
 634
 635 int
 636 main(int argc, char *argv[])
 637 {
 638     struct addrinfo hints;
 639     struct addrinfo *result, *rp;
 640     int sfd, s;
 641     struct sockaddr_storage peer_addr;
 642     socklen_t peer_addr_len;
 643     ssize_t nread;
 644     char buf[BUF_SIZE];
 645
 646     if (argc != 2) {
 647         fprintf(stderr, "Usage: %s port\\n", argv[0]);
 648         exit(EXIT_FAILURE);
 649     }
 650
 651     memset(&hints, 0, sizeof(struct addrinfo));
 652     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 653     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 654     hints.ai_flags = AI_PASSIVE;    /* For wildcard IP address */
 655     hints.ai_protocol = 0;          /* Any protocol */
 656     hints.ai_canonname = NULL;
 657     hints.ai_addr = NULL;
 658     hints.ai_next = NULL;
 659
 660     s = getaddrinfo(NULL, argv[1], &hints, &result);
 661     if (s != 0) {
 662         fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
 663         exit(EXIT_FAILURE);
 664     }
 665
 666     /* getaddrinfo() returns a list of address structures.
 667        Try each address until we successfully bind(2).
 668        If socket(2) (or bind(2)) fails, we (close the socket
 669        and) try the next address. */
 670
 671     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 672         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 673                 rp\->ai_protocol);
 674         if (sfd == \-1)
 675             continue;
 676
 677         if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0)
 678             break;                  /* Success */
 679
 680         close(sfd);
 681     }
 682
 683     if (rp == NULL) {               /* No address succeeded */
 684         fprintf(stderr, "Could not bind\\n");
 685         exit(EXIT_FAILURE);
 686     }
 687
 688     freeaddrinfo(result);           /* No longer needed */
 689
 690     /* Read datagrams and echo them back to sender */
 691
 692     for (;;) {
 693         peer_addr_len = sizeof(struct sockaddr_storage);
 694         nread = recvfrom(sfd, buf, BUF_SIZE, 0,
 695                 (struct sockaddr *) &peer_addr, &peer_addr_len);
 696         if (nread == \-1)
 697             continue;               /* Ignore failed request */
 698
 699         char host[NI_MAXHOST], service[NI_MAXSERV];
 700
 701         s = getnameinfo((struct sockaddr *) &peer_addr,
 702                         peer_addr_len, host, NI_MAXHOST,
 703                         service, NI_MAXSERV, NI_NUMERICSERV);
 704        if (s == 0)
 705             printf("Received %ld bytes from %s:%s\\n",
 706                     (long) nread, host, service);
 707         else
 708             fprintf(stderr, "getnameinfo: %s\\n", gai_strerror(s));
 709
 710         if (sendto(sfd, buf, nread, 0,
 711                     (struct sockaddr *) &peer_addr,
 712                     peer_addr_len) != nread)
 713             fprintf(stderr, "Error sending response\\n");
 714     }
 715 }
 716 .fi
 717 .SS Client program
 718 \&
 719 .nf
 720 #include <sys/types.h>
 721 #include <sys/socket.h>
 722 #include <netdb.h>
 723 #include <stdio.h>
 724 #include <stdlib.h>
 725 #include <unistd.h>
 726 #include <string.h>
 727
 728 #define BUF_SIZE 500
 729
 730 int
 731 main(int argc, char *argv[])
 732 {
 733     struct addrinfo hints;
 734     struct addrinfo *result, *rp;
 735     int sfd, s, j;
 736     size_t len;
 737     ssize_t nread;
 738     char buf[BUF_SIZE];
 739
 740     if (argc < 3) {
 741         fprintf(stderr, "Usage: %s host port msg...\\n", argv[0]);
 742         exit(EXIT_FAILURE);
 743     }
 744
 745     /* Obtain address(es) matching host/port */
 746
 747     memset(&hints, 0, sizeof(struct addrinfo));
 748     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 749     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 750     hints.ai_flags = 0;
 751     hints.ai_protocol = 0;          /* Any protocol */
 752
 753     s = getaddrinfo(argv[1], argv[2], &hints, &result);
 754     if (s != 0) {
 755         fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
 756         exit(EXIT_FAILURE);
 757     }
 758
 759     /* getaddrinfo() returns a list of address structures.
 760        Try each address until we successfully connect(2).
 761        If socket(2) (or connect(2)) fails, we (close the socket
 762        and) try the next address. */
 763
 764     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 765         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 766                      rp\->ai_protocol);
 767         if (sfd == \-1)
 768             continue;
 769
 770         if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1)
 771             break;                  /* Success */
 772
 773         close(sfd);
 774     }
 775
 776     if (rp == NULL) {               /* No address succeeded */
 777         fprintf(stderr, "Could not connect\\n");
 778         exit(EXIT_FAILURE);
 779     }
 780
 781     freeaddrinfo(result);           /* No longer needed */
 782
 783     /* Send remaining command\-line arguments as separate
 784        datagrams, and read responses from server */
 785
 786     for (j = 3; j < argc; j++) {
 787         len = strlen(argv[j]) + 1;
 788                 /* +1 for terminating null byte */
 789
 790         if (len + 1 > BUF_SIZE) {
 791             fprintf(stderr,
 792                     "Ignoring long message in argument %d\\n", j);
 793             continue;
 794         }
 795
 796         if (write(sfd, argv[j], len) != len) {
 797             fprintf(stderr, "partial/failed write\\n");
 798             exit(EXIT_FAILURE);
 799         }
 800
 801         nread = read(sfd, buf, BUF_SIZE);
 802         if (nread == \-1) {
 803             perror("read");
 804             exit(EXIT_FAILURE);
 805         }
 806
 807         printf("Received %ld bytes: %s\\n", (long) nread, buf);
 808     }
 809
 810     exit(EXIT_SUCCESS);
 811 }
 812 .fi
 813 .SH "SEE ALSO"
 814 .\" .BR getipnodebyaddr (3),
 815 .\" .BR getipnodebyname (3),
 816 .BR getaddrinfo_a (3),
 817 .BR gethostbyname (3),
 818 .BR getnameinfo (3),
 819 .BR inet (3),
 820 .BR hostname (7),
 821 .BR ip (7)