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