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 2013-01-15 "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 gethostbyname (3)
  93 and
  94 .BR getservbyname (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     socklen_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 The loopback address is not considered for this case as valid
 382 as a configured address.
 383 .PP
 384 If
 385 .I hint.ai_flags
 386 specifies the
 387 .B AI_V4MAPPED
 388 flag, and
 389 .I hints.ai_family
 390 was specified as
 391 .BR AF_INET6 ,
 392 and no matching IPv6 addresses could be found,
 393 then return IPv4-mapped IPv6 addresses in the list pointed to by
 394 .IR res .
 395 If both
 396 .B AI_V4MAPPED
 397 and
 398 .B AI_ALL
 399 are specified in
 400 .IR hints.ai_flags ,
 401 then return both IPv6 and IPv4-mapped IPv6 addresses
 402 in the list pointed to by
 403 .IR res .
 404 .B AI_ALL
 405 is ignored if
 406 .B AI_V4MAPPED
 407 is not also specified.
 408 .PP
 409 The
 410 .BR freeaddrinfo ()
 411 function frees the memory that was allocated
 412 for the dynamically allocated linked list
 413 .IR res .
 414 .SS "Extensions to getaddrinfo() for Internationalized Domain Names"
 415 .PP
 416 Starting with glibc 2.3.4,
 417 .BR getaddrinfo ()
 418 has been extended to selectively allow the incoming and outgoing
 419 hostnames to be transparently converted to and from the
 420 Internationalized Domain Name (IDN) format (see RFC 3490,
 421 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
 422 Four new flags are defined:
 423 .TP
 424 .B AI_IDN
 425 If this flag is specified, then the node name given in
 426 .I node
 427 is converted to IDN format if necessary.
 428 The source encoding is that of the current locale.
 429
 430 If the input name contains non-ASCII characters, then the IDN encoding
 431 is used.
 432 Those parts of the node name (delimited by dots) that contain
 433 non-ASCII characters are encoded using ASCII Compatible Encoding (ACE)
 434 before being passed to the name resolution functions.
 435 .\" Implementation Detail:
 436 .\" To minimize effects on system performance the implementation might
 437 .\" want to check whether the input string contains any non-ASCII
 438 .\" characters.  If there are none the IDN step can be skipped completely.
 439 .\" On systems which allow not-ASCII safe encodings for a locale this
 440 .\" might be a problem.
 441 .TP
 442 .B AI_CANONIDN
 443 After a successful name lookup, and if the
 444 .B AI_CANONNAME
 445 flag was specified,
 446 .BR getaddrinfo ()
 447 will return the canonical name of the
 448 node corresponding to the
 449 .I addrinfo
 450 structure value passed back.
 451 The return value is an exact copy of the value returned by the name
 452 resolution function.
 453
 454 If the name is encoded using ACE, then it will contain the
 455 .I xn\-\-
 456 prefix for one or more components of the name.
 457 To convert these components into a readable form the
 458 .B AI_CANONIDN
 459 flag can be passed in addition to
 460 .BR AI_CANONNAME .
 461 The resulting string is encoded using the current locale's encoding.
 462 .\"
 463 .\"Implementation Detail:
 464 .\"If no component of the returned name starts with xn\-\- the IDN
 465 .\"step can be skipped, therefore avoiding unnecessary slowdowns.
 466 .TP
 467 .BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES
 468 Setting these flags will enable the
 469 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
 470 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
 471 conforming hostname)
 472 flags respectively to be used in the IDNA handling.
 473 .SH RETURN VALUE
 474 .\" FIXME glibc defines the following additional errors, some which
 475 .\" can probably be returned by getaddrinfo(); they need to
 476 .\" be documented.
 477 .\" #ifdef __USE_GNU
 478 .\" #define EAI_INPROGRESS  -100  /* Processing request in progress.  */
 479 .\" #define EAI_CANCELED    -101  /* Request canceled.  */
 480 .\" #define EAI_NOTCANCELED -102  /* Request not canceled.  */
 481 .\" #define EAI_ALLDONE     -103  /* All requests done.  */
 482 .\" #define EAI_INTR        -104  /* Interrupted by a signal.  */
 483 .\" #define EAI_IDN_ENCODE  -105  /* IDN encoding failed.  */
 484 .\" #endif
 485 .BR getaddrinfo ()
 486 returns 0 if it succeeds, or one of the following nonzero error codes:
 487 .TP
 488 .B EAI_ADDRFAMILY
 489 .\" Not in SUSv3
 490 The specified network host does not have any network addresses in the
 491 requested address family.
 492 .TP
 493 .B EAI_AGAIN
 494 The name server returned a temporary failure indication.
 495 Try again later.
 496 .TP
 497 .B EAI_BADFLAGS
 498 .I hints.ai_flags
 499 contains invalid flags; or,
 500 .I hints.ai_flags
 501 included
 502 .B AI_CANONNAME
 503 and
 504 .I name
 505 was NULL.
 506 .TP
 507 .B EAI_FAIL
 508 The name server returned a permanent failure indication.
 509 .TP
 510 .B EAI_FAMILY
 511 The requested address family is not supported.
 512 .TP
 513 .B EAI_MEMORY
 514 Out of memory.
 515 .TP
 516 .B EAI_NODATA
 517 .\" Not in SUSv3
 518 The specified network host exists, but does not have any
 519 network addresses defined.
 520 .TP
 521 .B EAI_NONAME
 522 The
 523 .I node
 524 or
 525 .I service
 526 is not known; or both
 527 .I node
 528 and
 529 .I service
 530 are NULL; or
 531 .B AI_NUMERICSERV
 532 was specified in
 533 .I hints.ai_flags
 534 and
 535 .I service
 536 was not a numeric port-number string.
 537 .TP
 538 .B EAI_SERVICE
 539 The requested service is not available for the requested socket type.
 540 It may be available through another socket type.
 541 For example, this error could occur if
 542 .I service
 543 was "shell" (a service only available on stream sockets), and either
 544 .I hints.ai_protocol
 545 was
 546 .BR IPPROTO_UDP ,
 547 or
 548 .I hints.ai_socktype
 549 was
 550 .BR SOCK_DGRAM ;
 551 or the error could occur if
 552 .I service
 553 was not NULL, and
 554 .I hints.ai_socktype
 555 was
 556 .BR SOCK_RAW
 557 (a socket type that does not support the concept of services).
 558 .TP
 559 .B EAI_SOCKTYPE
 560 The requested socket type is not supported.
 561 This could occur, for example, if
 562 .I hints.ai_socktype
 563 and
 564 .I hints.ai_protocol
 565 are inconsistent (e.g.,
 566 .BR SOCK_DGRAM
 567 and
 568 .BR IPPROTO_TCP ,
 569 respectively).
 570 .TP
 571 .B EAI_SYSTEM
 572 Other system error, check
 573 .I errno
 574 for details.
 575 .PP
 576 The
 577 .BR gai_strerror ()
 578 function translates these error codes to a human readable string,
 579 suitable for error reporting.
 580 .SH FILES
 581 .I /etc/gai.conf
 582 .SH CONFORMING TO
 583 POSIX.1-2001.
 584 The
 585 .BR getaddrinfo ()
 586 function is documented in RFC\ 2553.
 587 .SH NOTES
 588 .BR getaddrinfo ()
 589 supports the
 590 .IB address % scope-id
 591 notation for specifying the IPv6 scope-ID.
 592
 593 .BR AI_ADDRCONFIG ,
 594 .BR AI_ALL ,
 595 and
 596 .B AI_V4MAPPED
 597 are available since glibc 2.3.3.
 598 .B AI_NUMERICSERV
 599 is available since glibc 2.3.4.
 600
 601 According to POSIX.1-2001, specifying
 602 .I hints
 603 as NULL should cause
 604 .I ai_flags
 605 to be assumed as 0.
 606 The GNU C library instead assumes a value of
 607 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)"
 608 for this case,
 609 since this value is considered an improvement on the specification.
 610 .SH EXAMPLE
 611 .\" getnameinfo.3 refers to this example
 612 .\" socket.2 refers to this example
 613 .\" bind.2 refers to this example
 614 .\" connect.2 refers to this example
 615 .\" recvfrom.2 refers to this example
 616 .\" sendto.2 refers to this example
 617 The following programs demonstrate the use of
 618 .BR getaddrinfo (),
 619 .BR gai_strerror (),
 620 .BR freeaddrinfo (),
 621 and
 622 .BR getnameinfo (3).
 623 The programs are an echo server and client for UDP datagrams.
 624 .SS Server program
 625 \&
 626 .nf
 627 #include <sys/types.h>
 628 #include <stdio.h>
 629 #include <stdlib.h>
 630 #include <unistd.h>
 631 #include <string.h>
 632 #include <sys/socket.h>
 633 #include <netdb.h>
 634
 635 #define BUF_SIZE 500
 636
 637 int
 638 main(int argc, char *argv[])
 639 {
 640     struct addrinfo hints;
 641     struct addrinfo *result, *rp;
 642     int sfd, s;
 643     struct sockaddr_storage peer_addr;
 644     socklen_t peer_addr_len;
 645     ssize_t nread;
 646     char buf[BUF_SIZE];
 647
 648     if (argc != 2) {
 649         fprintf(stderr, "Usage: %s port\\n", argv[0]);
 650         exit(EXIT_FAILURE);
 651     }
 652
 653     memset(&hints, 0, sizeof(struct addrinfo));
 654     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 655     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 656     hints.ai_flags = AI_PASSIVE;    /* For wildcard IP address */
 657     hints.ai_protocol = 0;          /* Any protocol */
 658     hints.ai_canonname = NULL;
 659     hints.ai_addr = NULL;
 660     hints.ai_next = NULL;
 661
 662     s = getaddrinfo(NULL, argv[1], &hints, &result);
 663     if (s != 0) {
 664         fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
 665         exit(EXIT_FAILURE);
 666     }
 667
 668     /* getaddrinfo() returns a list of address structures.
 669        Try each address until we successfully bind(2).
 670        If socket(2) (or bind(2)) fails, we (close the socket
 671        and) try the next address. */
 672
 673     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 674         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 675                 rp\->ai_protocol);
 676         if (sfd == \-1)
 677             continue;
 678
 679         if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0)
 680             break;                  /* Success */
 681
 682         close(sfd);
 683     }
 684
 685     if (rp == NULL) {               /* No address succeeded */
 686         fprintf(stderr, "Could not bind\\n");
 687         exit(EXIT_FAILURE);
 688     }
 689
 690     freeaddrinfo(result);           /* No longer needed */
 691
 692     /* Read datagrams and echo them back to sender */
 693
 694     for (;;) {
 695         peer_addr_len = sizeof(struct sockaddr_storage);
 696         nread = recvfrom(sfd, buf, BUF_SIZE, 0,
 697                 (struct sockaddr *) &peer_addr, &peer_addr_len);
 698         if (nread == \-1)
 699             continue;               /* Ignore failed request */
 700
 701         char host[NI_MAXHOST], service[NI_MAXSERV];
 702
 703         s = getnameinfo((struct sockaddr *) &peer_addr,
 704                         peer_addr_len, host, NI_MAXHOST,
 705                         service, NI_MAXSERV, NI_NUMERICSERV);
 706        if (s == 0)
 707             printf("Received %ld bytes from %s:%s\\n",
 708                     (long) nread, host, service);
 709         else
 710             fprintf(stderr, "getnameinfo: %s\\n", gai_strerror(s));
 711
 712         if (sendto(sfd, buf, nread, 0,
 713                     (struct sockaddr *) &peer_addr,
 714                     peer_addr_len) != nread)
 715             fprintf(stderr, "Error sending response\\n");
 716     }
 717 }
 718 .fi
 719 .SS Client program
 720 \&
 721 .nf
 722 #include <sys/types.h>
 723 #include <sys/socket.h>
 724 #include <netdb.h>
 725 #include <stdio.h>
 726 #include <stdlib.h>
 727 #include <unistd.h>
 728 #include <string.h>
 729
 730 #define BUF_SIZE 500
 731
 732 int
 733 main(int argc, char *argv[])
 734 {
 735     struct addrinfo hints;
 736     struct addrinfo *result, *rp;
 737     int sfd, s, j;
 738     size_t len;
 739     ssize_t nread;
 740     char buf[BUF_SIZE];
 741
 742     if (argc < 3) {
 743         fprintf(stderr, "Usage: %s host port msg...\\n", argv[0]);
 744         exit(EXIT_FAILURE);
 745     }
 746
 747     /* Obtain address(es) matching host/port */
 748
 749     memset(&hints, 0, sizeof(struct addrinfo));
 750     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 751     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 752     hints.ai_flags = 0;
 753     hints.ai_protocol = 0;          /* Any protocol */
 754
 755     s = getaddrinfo(argv[1], argv[2], &hints, &result);
 756     if (s != 0) {
 757         fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
 758         exit(EXIT_FAILURE);
 759     }
 760
 761     /* getaddrinfo() returns a list of address structures.
 762        Try each address until we successfully connect(2).
 763        If socket(2) (or connect(2)) fails, we (close the socket
 764        and) try the next address. */
 765
 766     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 767         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 768                      rp\->ai_protocol);
 769         if (sfd == \-1)
 770             continue;
 771
 772         if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1)
 773             break;                  /* Success */
 774
 775         close(sfd);
 776     }
 777
 778     if (rp == NULL) {               /* No address succeeded */
 779         fprintf(stderr, "Could not connect\\n");
 780         exit(EXIT_FAILURE);
 781     }
 782
 783     freeaddrinfo(result);           /* No longer needed */
 784
 785     /* Send remaining command\-line arguments as separate
 786        datagrams, and read responses from server */
 787
 788     for (j = 3; j < argc; j++) {
 789         len = strlen(argv[j]) + 1;
 790                 /* +1 for terminating null byte */
 791
 792         if (len + 1 > BUF_SIZE) {
 793             fprintf(stderr,
 794                     "Ignoring long message in argument %d\\n", j);
 795             continue;
 796         }
 797
 798         if (write(sfd, argv[j], len) != len) {
 799             fprintf(stderr, "partial/failed write\\n");
 800             exit(EXIT_FAILURE);
 801         }
 802
 803         nread = read(sfd, buf, BUF_SIZE);
 804         if (nread == \-1) {
 805             perror("read");
 806             exit(EXIT_FAILURE);
 807         }
 808
 809         printf("Received %ld bytes: %s\\n", (long) nread, buf);
 810     }
 811
 812     exit(EXIT_SUCCESS);
 813 }
 814 .fi
 815 .SH SEE ALSO
 816 .\" .BR getipnodebyaddr (3),
 817 .\" .BR getipnodebyname (3),
 818 .BR getaddrinfo_a (3),
 819 .BR gethostbyname (3),
 820 .BR getnameinfo (3),
 821 .BR inet (3),
 822 .BR gai.conf (5),
 823 .BR hostname (7),
 824 .BR ip (7)