original/man3/getaddrinfo.3

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