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