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