contrib/bind-9.2.4rc7/lib/lwres/man/lwres_getaddrinfo.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001, 2003  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- $Id: lwres_getaddrinfo.html,v 1.8.2.3 2004/03/15 04:45:02 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres_getaddrinfo</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 >lwres_getaddrinfo</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >lwres_getaddrinfo, lwres_freeaddrinfo&nbsp;--&nbsp;socket address structure to host and service name</DIV
  48 ><DIV
  49 CLASS="REFSYNOPSISDIV"
  50 ><A
  51 NAME="AEN12"
  52 ></A
  53 ><H2
  54 >Synopsis</H2
  55 ><DIV
  56 CLASS="FUNCSYNOPSIS"
  57 ><A
  58 NAME="AEN13"
  59 ></A
  60 ><P
  61 ></P
  62 ><PRE
  63 CLASS="FUNCSYNOPSISINFO"
  64 >#include &lt;lwres/netdb.h&gt;</PRE
  65 ><P
  66 ><CODE
  67 ><CODE
  68 CLASS="FUNCDEF"
  69 >int
  70 lwres_getaddrinfo</CODE
  71 >(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);</CODE
  72 ></P
  73 ><P
  74 ><CODE
  75 ><CODE
  76 CLASS="FUNCDEF"
  77 >void
  78 lwres_freeaddrinfo</CODE
  79 >(struct addrinfo *ai);</CODE
  80 ></P
  81 ><P
  82 ></P
  83 ></DIV
  84 ><P
  85 >If the operating system does not provide a
  86 <SPAN
  87 CLASS="TYPE"
  88 >struct addrinfo</SPAN
  89 >,
  90 the following structure is used:
  91
  92 <PRE
  93 CLASS="PROGRAMLISTING"
  94 >struct  addrinfo {
  95         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
  96         int             ai_family;      /* PF_xxx */
  97         int             ai_socktype;    /* SOCK_xxx */
  98         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  99         size_t          ai_addrlen;     /* length of ai_addr */
 100         char            *ai_canonname;  /* canonical name for hostname */
 101         struct sockaddr *ai_addr;       /* binary address */
 102         struct addrinfo *ai_next;       /* next structure in linked list */
 103 };</PRE
 104 ></P
 105 ></DIV
 106 ><DIV
 107 CLASS="REFSECT1"
 108 ><A
 109 NAME="AEN29"
 110 ></A
 111 ><H2
 112 >DESCRIPTION</H2
 113 ><P
 114 ><TT
 115 CLASS="FUNCTION"
 116 >lwres_getaddrinfo()</TT
 117 >
 118 is used to get a list of IP addresses and port numbers for host
 119 <TT
 120 CLASS="PARAMETER"
 121 ><I
 122 >hostname</I
 123 ></TT
 124 >
 125 and service
 126 <TT
 127 CLASS="PARAMETER"
 128 ><I
 129 >servname</I
 130 ></TT
 131 >.
 132
 133 The function is the lightweight resolver's implementation of
 134 <TT
 135 CLASS="FUNCTION"
 136 >getaddrinfo()</TT
 137 >
 138 as defined in RFC2133.
 139 <TT
 140 CLASS="PARAMETER"
 141 ><I
 142 >hostname</I
 143 ></TT
 144 >
 145 and
 146 <TT
 147 CLASS="PARAMETER"
 148 ><I
 149 >servname</I
 150 ></TT
 151 >
 152 are pointers to null-terminated
 153 strings or
 154 <SPAN
 155 CLASS="TYPE"
 156 >NULL</SPAN
 157 >.
 158
 159 <TT
 160 CLASS="PARAMETER"
 161 ><I
 162 >hostname</I
 163 ></TT
 164 >
 165 is either a host name or a numeric host address string: a dotted decimal
 166 IPv4 address or an IPv6 address.
 167 <TT
 168 CLASS="PARAMETER"
 169 ><I
 170 >servname</I
 171 ></TT
 172 >
 173 is either a decimal port number or a service name as listed in
 174 <TT
 175 CLASS="FILENAME"
 176 >/etc/services</TT
 177 >.</P
 178 ><P
 179 ><TT
 180 CLASS="PARAMETER"
 181 ><I
 182 >hints</I
 183 ></TT
 184 >
 185 is an optional pointer to a
 186 <SPAN
 187 CLASS="TYPE"
 188 >struct addrinfo</SPAN
 189 >.
 190 This structure can be used to provide hints concerning the type of socket
 191 that the caller supports or wishes to use.
 192 The caller can supply the following structure elements in
 193 <TT
 194 CLASS="PARAMETER"
 195 ><I
 196 >*hints</I
 197 ></TT
 198 >:
 199
 200 <P
 201 ></P
 202 ><DIV
 203 CLASS="VARIABLELIST"
 204 ><DL
 205 ><DT
 206 ><TT
 207 CLASS="CONSTANT"
 208 >ai_family</TT
 209 ></DT
 210 ><DD
 211 ><P
 212 >The protocol family that should be used.
 213 When
 214 <TT
 215 CLASS="CONSTANT"
 216 >ai_family</TT
 217 >
 218 is set to
 219 <SPAN
 220 CLASS="TYPE"
 221 >PF_UNSPEC</SPAN
 222 >,
 223 it means the caller will accept any protocol family supported by the
 224 operating system.</P
 225 ></DD
 226 ><DT
 227 ><TT
 228 CLASS="CONSTANT"
 229 >ai_socktype</TT
 230 ></DT
 231 ><DD
 232 ><P
 233 >denotes the type of socket &mdash;
 234 <SPAN
 235 CLASS="TYPE"
 236 >SOCK_STREAM</SPAN
 237 >,
 238 <SPAN
 239 CLASS="TYPE"
 240 >SOCK_DGRAM</SPAN
 241 >
 242 or
 243 <SPAN
 244 CLASS="TYPE"
 245 >SOCK_RAW</SPAN
 246 >
 247 &mdash; that is wanted.
 248 When
 249 <TT
 250 CLASS="CONSTANT"
 251 >ai_socktype</TT
 252 >
 253 is zero the caller will accept any socket type.</P
 254 ></DD
 255 ><DT
 256 ><TT
 257 CLASS="CONSTANT"
 258 >ai_protocol</TT
 259 ></DT
 260 ><DD
 261 ><P
 262 >indicates which transport protocol is wanted: IPPROTO_UDP or
 263 IPPROTO_TCP.
 264 If
 265 <TT
 266 CLASS="CONSTANT"
 267 >ai_protocol</TT
 268 >
 269 is zero the caller will accept any protocol.</P
 270 ></DD
 271 ><DT
 272 ><TT
 273 CLASS="CONSTANT"
 274 >ai_flags</TT
 275 ></DT
 276 ><DD
 277 ><P
 278 >Flag bits.
 279 If the
 280 <SPAN
 281 CLASS="TYPE"
 282 >AI_CANONNAME</SPAN
 283 >
 284 bit is set, a successful call to
 285 <TT
 286 CLASS="FUNCTION"
 287 >lwres_getaddrinfo()</TT
 288 >
 289 will return a null-terminated string containing the canonical name
 290 of the specified hostname in
 291 <TT
 292 CLASS="CONSTANT"
 293 >ai_canonname</TT
 294 >
 295 of the first
 296 <SPAN
 297 CLASS="TYPE"
 298 >addrinfo</SPAN
 299 >
 300 structure returned.
 301 Setting the
 302 <SPAN
 303 CLASS="TYPE"
 304 >AI_PASSIVE</SPAN
 305 >
 306 bit indicates that the returned socket address structure is intended
 307 for used in a call to
 308 <SPAN
 309 CLASS="CITEREFENTRY"
 310 ><SPAN
 311 CLASS="REFENTRYTITLE"
 312 >bind</SPAN
 313 >(2)</SPAN
 314 >.
 315
 316 In this case, if the hostname argument is a
 317 <SPAN
 318 CLASS="TYPE"
 319 >NULL</SPAN
 320 >
 321 pointer, then the IP address portion of the socket
 322 address structure will be set to
 323 <SPAN
 324 CLASS="TYPE"
 325 >INADDR_ANY</SPAN
 326 >
 327 for an IPv4 address or
 328 <SPAN
 329 CLASS="TYPE"
 330 >IN6ADDR_ANY_INIT</SPAN
 331 >
 332 for an IPv6 address.</P
 333 ><P
 334 >When
 335 <TT
 336 CLASS="CONSTANT"
 337 >ai_flags</TT
 338 >
 339 does not set the
 340 <SPAN
 341 CLASS="TYPE"
 342 >AI_PASSIVE</SPAN
 343 >
 344 bit, the returned socket address structure will be ready
 345 for use in a call to
 346 <SPAN
 347 CLASS="CITEREFENTRY"
 348 ><SPAN
 349 CLASS="REFENTRYTITLE"
 350 >connect</SPAN
 351 >(2)</SPAN
 352 >
 353 for a connection-oriented protocol or
 354 <SPAN
 355 CLASS="CITEREFENTRY"
 356 ><SPAN
 357 CLASS="REFENTRYTITLE"
 358 >connect</SPAN
 359 >(2)</SPAN
 360 >,
 361
 362 <SPAN
 363 CLASS="CITEREFENTRY"
 364 ><SPAN
 365 CLASS="REFENTRYTITLE"
 366 >sendto</SPAN
 367 >(2)</SPAN
 368 >,
 369
 370 or
 371 <SPAN
 372 CLASS="CITEREFENTRY"
 373 ><SPAN
 374 CLASS="REFENTRYTITLE"
 375 >sendmsg</SPAN
 376 >(2)</SPAN
 377 >
 378 if a connectionless protocol was chosen.
 379 The IP address portion of the socket address structure will be
 380 set to the loopback address if
 381 <TT
 382 CLASS="PARAMETER"
 383 ><I
 384 >hostname</I
 385 ></TT
 386 >
 387 is a
 388 <SPAN
 389 CLASS="TYPE"
 390 >NULL</SPAN
 391 >
 392 pointer and
 393 <SPAN
 394 CLASS="TYPE"
 395 >AI_PASSIVE</SPAN
 396 >
 397 is not set in
 398 <TT
 399 CLASS="CONSTANT"
 400 >ai_flags</TT
 401 >.</P
 402 ><P
 403 >If
 404 <TT
 405 CLASS="CONSTANT"
 406 >ai_flags</TT
 407 >
 408 is set to
 409 <SPAN
 410 CLASS="TYPE"
 411 >AI_NUMERICHOST</SPAN
 412 >
 413 it indicates that
 414 <TT
 415 CLASS="PARAMETER"
 416 ><I
 417 >hostname</I
 418 ></TT
 419 >
 420 should be treated as a numeric string defining an IPv4 or IPv6 address
 421 and no name resolution should be attempted.</P
 422 ></DD
 423 ></DL
 424 ></DIV
 425 ></P
 426 ><P
 427 >All other elements of the <SPAN
 428 CLASS="TYPE"
 429 >struct addrinfo</SPAN
 430 > passed
 431 via <TT
 432 CLASS="PARAMETER"
 433 ><I
 434 >hints</I
 435 ></TT
 436 > must be zero.</P
 437 ><P
 438 >A <TT
 439 CLASS="PARAMETER"
 440 ><I
 441 >hints</I
 442 ></TT
 443 > of <SPAN
 444 CLASS="TYPE"
 445 >NULL</SPAN
 446 > is treated as if
 447 the caller provided a <SPAN
 448 CLASS="TYPE"
 449 >struct addrinfo</SPAN
 450 > initialized to zero
 451 with <TT
 452 CLASS="CONSTANT"
 453 >ai_family</TT
 454 >set to
 455 <TT
 456 CLASS="CONSTANT"
 457 >PF_UNSPEC</TT
 458 >.</P
 459 ><P
 460 >After a successful call to
 461 <TT
 462 CLASS="FUNCTION"
 463 >lwres_getaddrinfo()</TT
 464 >,
 465 <TT
 466 CLASS="PARAMETER"
 467 ><I
 468 >*res</I
 469 ></TT
 470 >
 471 is a pointer to a linked list of one or more
 472 <SPAN
 473 CLASS="TYPE"
 474 >addrinfo</SPAN
 475 >
 476 structures.
 477 Each
 478 <SPAN
 479 CLASS="TYPE"
 480 >struct addrinfo</SPAN
 481 >
 482 in this list cn be processed by following
 483 the
 484 <TT
 485 CLASS="CONSTANT"
 486 >ai_next</TT
 487 >
 488 pointer, until a
 489 <SPAN
 490 CLASS="TYPE"
 491 >NULL</SPAN
 492 >
 493 pointer is encountered.
 494 The three members
 495 <TT
 496 CLASS="CONSTANT"
 497 >ai_family</TT
 498 >,
 499 <TT
 500 CLASS="CONSTANT"
 501 >ai_socktype</TT
 502 >,
 503 and
 504 <TT
 505 CLASS="CONSTANT"
 506 >ai_protocol</TT
 507 >
 508 in each
 509 returned
 510 <SPAN
 511 CLASS="TYPE"
 512 >addrinfo</SPAN
 513 >
 514 structure contain the corresponding arguments for a call to
 515 <SPAN
 516 CLASS="CITEREFENTRY"
 517 ><SPAN
 518 CLASS="REFENTRYTITLE"
 519 >socket</SPAN
 520 >(2)</SPAN
 521 >.
 522 For each
 523 <SPAN
 524 CLASS="TYPE"
 525 >addrinfo</SPAN
 526 >
 527 structure in the list, the
 528 <TT
 529 CLASS="CONSTANT"
 530 >ai_addr</TT
 531 >
 532 member points to a filled-in socket address structure of length
 533 <TT
 534 CLASS="CONSTANT"
 535 >ai_addrlen</TT
 536 >.</P
 537 ><P
 538 >All of the information returned by
 539 <TT
 540 CLASS="FUNCTION"
 541 >lwres_getaddrinfo()</TT
 542 >
 543 is dynamically allocated: the addrinfo structures, and the socket
 544 address structures and canonical host name strings pointed to by the
 545 <TT
 546 CLASS="CONSTANT"
 547 >addrinfo</TT
 548 >structures.
 549 Memory allocated for the dynamically allocated structures created by
 550 a successful call to
 551 <TT
 552 CLASS="FUNCTION"
 553 >lwres_getaddrinfo()</TT
 554 >
 555 is released by
 556 <TT
 557 CLASS="FUNCTION"
 558 >lwres_freeaddrinfo()</TT
 559 >.
 560 <TT
 561 CLASS="PARAMETER"
 562 ><I
 563 >ai</I
 564 ></TT
 565 >
 566 is a pointer to a
 567 <SPAN
 568 CLASS="TYPE"
 569 >struct addrinfo</SPAN
 570 >
 571 created by a call to
 572 <TT
 573 CLASS="FUNCTION"
 574 >lwres_getaddrinfo()</TT
 575 >.</P
 576 ></DIV
 577 ><DIV
 578 CLASS="REFSECT1"
 579 ><A
 580 NAME="AEN142"
 581 ></A
 582 ><H2
 583 >RETURN VALUES</H2
 584 ><P
 585 ><TT
 586 CLASS="FUNCTION"
 587 >lwres_getaddrinfo()</TT
 588 >
 589 returns zero on success or one of the error codes listed in
 590 <SPAN
 591 CLASS="CITEREFENTRY"
 592 ><SPAN
 593 CLASS="REFENTRYTITLE"
 594 >gai_strerror</SPAN
 595 >(3)</SPAN
 596 >
 597 if an error occurs.
 598 If both
 599 <TT
 600 CLASS="PARAMETER"
 601 ><I
 602 >hostname</I
 603 ></TT
 604 >
 605 and
 606 <TT
 607 CLASS="PARAMETER"
 608 ><I
 609 >servname</I
 610 ></TT
 611 >
 612 are
 613 <SPAN
 614 CLASS="TYPE"
 615 >NULL</SPAN
 616 >
 617 <TT
 618 CLASS="FUNCTION"
 619 >lwres_getaddrinfo()</TT
 620 >
 621 returns
 622 <SPAN
 623 CLASS="ERRORCODE"
 624 >EAI_NONAME</SPAN
 625 >.&#13;</P
 626 ></DIV
 627 ><DIV
 628 CLASS="REFSECT1"
 629 ><A
 630 NAME="AEN154"
 631 ></A
 632 ><H2
 633 >SEE ALSO</H2
 634 ><P
 635 ><SPAN
 636 CLASS="CITEREFENTRY"
 637 ><SPAN
 638 CLASS="REFENTRYTITLE"
 639 >lwres</SPAN
 640 >(3)</SPAN
 641 >,
 642
 643 <SPAN
 644 CLASS="CITEREFENTRY"
 645 ><SPAN
 646 CLASS="REFENTRYTITLE"
 647 >lwres_getaddrinfo</SPAN
 648 >(3)</SPAN
 649 >,
 650
 651 <SPAN
 652 CLASS="CITEREFENTRY"
 653 ><SPAN
 654 CLASS="REFENTRYTITLE"
 655 >lwres_freeaddrinfo</SPAN
 656 >(3)</SPAN
 657 >,
 658
 659 <SPAN
 660 CLASS="CITEREFENTRY"
 661 ><SPAN
 662 CLASS="REFENTRYTITLE"
 663 >lwres_gai_strerror</SPAN
 664 >(3)</SPAN
 665 >,
 666
 667 <SPAN
 668 CLASS="CITEREFENTRY"
 669 ><SPAN
 670 CLASS="REFENTRYTITLE"
 671 >RFC2133</SPAN
 672 ></SPAN
 673 >,
 674
 675 <SPAN
 676 CLASS="CITEREFENTRY"
 677 ><SPAN
 678 CLASS="REFENTRYTITLE"
 679 >getservbyname</SPAN
 680 >(3)</SPAN
 681 >,
 682
 683 <SPAN
 684 CLASS="CITEREFENTRY"
 685 ><SPAN
 686 CLASS="REFENTRYTITLE"
 687 >bind</SPAN
 688 >(2)</SPAN
 689 >,
 690
 691 <SPAN
 692 CLASS="CITEREFENTRY"
 693 ><SPAN
 694 CLASS="REFENTRYTITLE"
 695 >connect</SPAN
 696 >(2)</SPAN
 697 >,
 698
 699 <SPAN
 700 CLASS="CITEREFENTRY"
 701 ><SPAN
 702 CLASS="REFENTRYTITLE"
 703 >sendto</SPAN
 704 >(2)</SPAN
 705 >,
 706
 707 <SPAN
 708 CLASS="CITEREFENTRY"
 709 ><SPAN
 710 CLASS="REFENTRYTITLE"
 711 >sendmsg</SPAN
 712 >(2)</SPAN
 713 >,
 714
 715 <SPAN
 716 CLASS="CITEREFENTRY"
 717 ><SPAN
 718 CLASS="REFENTRYTITLE"
 719 >socket</SPAN
 720 >(2)</SPAN
 721 >.</P
 722 ></DIV
 723 ></BODY
 724 ></HTML
 725 >