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 .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support
  41 .\"           and is SCTP support now also there?
  42 .\"
  43 .TH GETADDRINFO 3 2014-04-06 "GNU" "Linux Programmer's Manual"
  44 .SH NAME
  45 getaddrinfo, freeaddrinfo, gai_strerror \- network address and
  46 service translation
  47 .SH SYNOPSIS
  48 .nf
  49 .B #include <sys/types.h>
  50 .B #include <sys/socket.h>
  51 .B #include <netdb.h>
  52 .sp
  53 .BI "int getaddrinfo(const char *" "node" ", const char *" "service" ,
  54 .BI "                const struct addrinfo *" "hints" ,
  55 .BI "                struct addrinfo **" "res" );
  56 .sp
  57 .BI "void freeaddrinfo(struct addrinfo *" "res" );
  58 .sp
  59 .BI "const char *gai_strerror(int " "errcode" );
  60 .fi
  61 .sp
  62 .in -4n
  63 Feature Test Macro Requirements for glibc (see
  64 .BR feature_test_macros (7)):
  65 .ad l
  66 .in
  67 .sp
  68 .BR getaddrinfo (),
  69 .BR freeaddrinfo (),
  70 .BR gai_strerror ():
  71 .RS 4
  72 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
  73 .RE
  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 .sp
 107 .in +4n
 108 .nf
 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 .fi
 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 hosts'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
 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
 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
 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
 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 CONFORMING TO
 595 POSIX.1-2001.
 596 The
 597 .BR getaddrinfo ()
 598 function is documented in RFC\ 2553.
 599 .SH NOTES
 600 .BR getaddrinfo ()
 601 supports the
 602 .IB address % scope-id
 603 notation for specifying the IPv6 scope-ID.
 604
 605 .BR AI_ADDRCONFIG ,
 606 .BR AI_ALL ,
 607 and
 608 .B AI_V4MAPPED
 609 are available since glibc 2.3.3.
 610 .B AI_NUMERICSERV
 611 is available since glibc 2.3.4.
 612
 613 According to POSIX.1-2001, specifying
 614 .I hints
 615 as NULL should cause
 616 .I ai_flags
 617 to be assumed as 0.
 618 The GNU C library instead assumes a value of
 619 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)"
 620 for this case,
 621 since this value is considered an improvement on the specification.
 622 .SH EXAMPLE
 623 .\" getnameinfo.3 refers to this example
 624 .\" socket.2 refers to this example
 625 .\" bind.2 refers to this example
 626 .\" connect.2 refers to this example
 627 .\" recvfrom.2 refers to this example
 628 .\" sendto.2 refers to this example
 629 The following programs demonstrate the use of
 630 .BR getaddrinfo (),
 631 .BR gai_strerror (),
 632 .BR freeaddrinfo (),
 633 and
 634 .BR getnameinfo (3).
 635 The programs are an echo server and client for UDP datagrams.
 636 .SS Server program
 637 \&
 638 .nf
 639 #include <sys/types.h>
 640 #include <stdio.h>
 641 #include <stdlib.h>
 642 #include <unistd.h>
 643 #include <string.h>
 644 #include <sys/socket.h>
 645 #include <netdb.h>
 646
 647 #define BUF_SIZE 500
 648
 649 int
 650 main(int argc, char *argv[])
 651 {
 652     struct addrinfo hints;
 653     struct addrinfo *result, *rp;
 654     int sfd, s;
 655     struct sockaddr_storage peer_addr;
 656     socklen_t peer_addr_len;
 657     ssize_t nread;
 658     char buf[BUF_SIZE];
 659
 660     if (argc != 2) {
 661         fprintf(stderr, "Usage: %s port\\n", argv[0]);
 662         exit(EXIT_FAILURE);
 663     }
 664
 665     memset(&hints, 0, sizeof(struct addrinfo));
 666     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 667     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 668     hints.ai_flags = AI_PASSIVE;    /* For wildcard IP address */
 669     hints.ai_protocol = 0;          /* Any protocol */
 670     hints.ai_canonname = NULL;
 671     hints.ai_addr = NULL;
 672     hints.ai_next = NULL;
 673
 674     s = getaddrinfo(NULL, argv[1], &hints, &result);
 675     if (s != 0) {
 676         fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
 677         exit(EXIT_FAILURE);
 678     }
 679
 680     /* getaddrinfo() returns a list of address structures.
 681        Try each address until we successfully bind(2).
 682        If socket(2) (or bind(2)) fails, we (close the socket
 683        and) try the next address. */
 684
 685     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 686         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 687                 rp\->ai_protocol);
 688         if (sfd == \-1)
 689             continue;
 690
 691         if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0)
 692             break;                  /* Success */
 693
 694         close(sfd);
 695     }
 696
 697     if (rp == NULL) {               /* No address succeeded */
 698         fprintf(stderr, "Could not bind\\n");
 699         exit(EXIT_FAILURE);
 700     }
 701
 702     freeaddrinfo(result);           /* No longer needed */
 703
 704     /* Read datagrams and echo them back to sender */
 705
 706     for (;;) {
 707         peer_addr_len = sizeof(struct sockaddr_storage);
 708         nread = recvfrom(sfd, buf, BUF_SIZE, 0,
 709                 (struct sockaddr *) &peer_addr, &peer_addr_len);
 710         if (nread == \-1)
 711             continue;               /* Ignore failed request */
 712
 713         char host[NI_MAXHOST], service[NI_MAXSERV];
 714
 715         s = getnameinfo((struct sockaddr *) &peer_addr,
 716                         peer_addr_len, host, NI_MAXHOST,
 717                         service, NI_MAXSERV, NI_NUMERICSERV);
 718        if (s == 0)
 719             printf("Received %zd bytes from %s:%s\\n",
 720                     nread, host, service);
 721         else
 722             fprintf(stderr, "getnameinfo: %s\\n", gai_strerror(s));
 723
 724         if (sendto(sfd, buf, nread, 0,
 725                     (struct sockaddr *) &peer_addr,
 726                     peer_addr_len) != nread)
 727             fprintf(stderr, "Error sending response\\n");
 728     }
 729 }
 730 .fi
 731 .SS Client program
 732 \&
 733 .nf
 734 #include <sys/types.h>
 735 #include <sys/socket.h>
 736 #include <netdb.h>
 737 #include <stdio.h>
 738 #include <stdlib.h>
 739 #include <unistd.h>
 740 #include <string.h>
 741
 742 #define BUF_SIZE 500
 743
 744 int
 745 main(int argc, char *argv[])
 746 {
 747     struct addrinfo hints;
 748     struct addrinfo *result, *rp;
 749     int sfd, s, j;
 750     size_t len;
 751     ssize_t nread;
 752     char buf[BUF_SIZE];
 753
 754     if (argc < 3) {
 755         fprintf(stderr, "Usage: %s host port msg...\\n", argv[0]);
 756         exit(EXIT_FAILURE);
 757     }
 758
 759     /* Obtain address(es) matching host/port */
 760
 761     memset(&hints, 0, sizeof(struct addrinfo));
 762     hints.ai_family = AF_UNSPEC;    /* Allow IPv4 or IPv6 */
 763     hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
 764     hints.ai_flags = 0;
 765     hints.ai_protocol = 0;          /* Any protocol */
 766
 767     s = getaddrinfo(argv[1], argv[2], &hints, &result);
 768     if (s != 0) {
 769         fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
 770         exit(EXIT_FAILURE);
 771     }
 772
 773     /* getaddrinfo() returns a list of address structures.
 774        Try each address until we successfully connect(2).
 775        If socket(2) (or connect(2)) fails, we (close the socket
 776        and) try the next address. */
 777
 778     for (rp = result; rp != NULL; rp = rp\->ai_next) {
 779         sfd = socket(rp\->ai_family, rp\->ai_socktype,
 780                      rp\->ai_protocol);
 781         if (sfd == \-1)
 782             continue;
 783
 784         if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1)
 785             break;                  /* Success */
 786
 787         close(sfd);
 788     }
 789
 790     if (rp == NULL) {               /* No address succeeded */
 791         fprintf(stderr, "Could not connect\\n");
 792         exit(EXIT_FAILURE);
 793     }
 794
 795     freeaddrinfo(result);           /* No longer needed */
 796
 797     /* Send remaining command\-line arguments as separate
 798        datagrams, and read responses from server */
 799
 800     for (j = 3; j < argc; j++) {
 801         len = strlen(argv[j]) + 1;
 802                 /* +1 for terminating null byte */
 803
 804         if (len + 1 > BUF_SIZE) {
 805             fprintf(stderr,
 806                     "Ignoring long message in argument %d\\n", j);
 807             continue;
 808         }
 809
 810         if (write(sfd, argv[j], len) != len) {
 811             fprintf(stderr, "partial/failed write\\n");
 812             exit(EXIT_FAILURE);
 813         }
 814
 815         nread = read(sfd, buf, BUF_SIZE);
 816         if (nread == \-1) {
 817             perror("read");
 818             exit(EXIT_FAILURE);
 819         }
 820
 821         printf("Received %zd bytes: %s\\n", nread, buf);
 822     }
 823
 824     exit(EXIT_SUCCESS);
 825 }
 826 .fi
 827 .SH SEE ALSO
 828 .\" .BR getipnodebyaddr (3),
 829 .\" .BR getipnodebyname (3),
 830 .BR getaddrinfo_a (3),
 831 .BR gethostbyname (3),
 832 .BR getnameinfo (3),
 833 .BR inet (3),
 834 .BR gai.conf (5),
 835 .BR hostname (7),
 836 .BR ip (7)
 837 .SH COLOPHON
 838 This page is part of release 3.68 of the Linux
 839 .I man-pages
 840 project.
 841 A description of the project,
 842 information about reporting bugs,
 843 and the latest version of this page,
 844 can be found at
 845 \%http://www.kernel.org/doc/man\-pages/.