lib/liblwres/man/lwres_gethostent.html

   1 <!--
   2  - Copyright (C) 2000, 2001  Internet Software Consortium.
   3  -
   4  - Permission to use, copy, modify, and distribute this software for any
   5  - purpose with or without fee is hereby granted, provided that the above
   6  - copyright notice and this permission notice appear in all copies.
   7  -
   8  - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
   9  - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  10  - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  11  - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  13  - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  14  - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  15  - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17 <HTML
  18 ><HEAD
  19 ><TITLE
  20 >lwres_gethostent</TITLE
  21 ><META
  22 NAME="GENERATOR"
  23 CONTENT="Modular DocBook HTML Stylesheet Version 1.61
  24 "></HEAD
  25 ><BODY
  26 CLASS="REFENTRY"
  27 BGCOLOR="#FFFFFF"
  28 TEXT="#000000"
  29 LINK="#0000FF"
  30 VLINK="#840084"
  31 ALINK="#0000FF"
  32 ><H1
  33 ><A
  34 NAME="AEN1"
  35 >lwres_gethostent</A
  36 ></H1
  37 ><DIV
  38 CLASS="REFNAMEDIV"
  39 ><A
  40 NAME="AEN8"
  41 ></A
  42 ><H2
  43 >Name</H2
  44 >lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r&nbsp;--&nbsp;lightweight resolver get network host entry</DIV
  45 ><DIV
  46 CLASS="REFSYNOPSISDIV"
  47 ><A
  48 NAME="AEN21"
  49 ></A
  50 ><H2
  51 >Synopsis</H2
  52 ><DIV
  53 CLASS="FUNCSYNOPSIS"
  54 ><A
  55 NAME="AEN22"
  56 ></A
  57 ><P
  58 ></P
  59 ><PRE
  60 CLASS="FUNCSYNOPSISINFO"
  61 >#include &lt;lwres/netdb.h&gt;</PRE
  62 ><P
  63 ><CODE
  64 ><CODE
  65 CLASS="FUNCDEF"
  66 >struct hostent *
  67 lwres_gethostbyname</CODE
  68 >(const char *name);</CODE
  69 ></P
  70 ><P
  71 ><CODE
  72 ><CODE
  73 CLASS="FUNCDEF"
  74 >struct hostent *
  75 lwres_gethostbyname2</CODE
  76 >(const char *name, int af);</CODE
  77 ></P
  78 ><P
  79 ><CODE
  80 ><CODE
  81 CLASS="FUNCDEF"
  82 >struct hostent *
  83 lwres_gethostbyaddr</CODE
  84 >(const char *addr, int len, int type);</CODE
  85 ></P
  86 ><P
  87 ><CODE
  88 ><CODE
  89 CLASS="FUNCDEF"
  90 >struct hostent *
  91 lwres_gethostent</CODE
  92 >(void);</CODE
  93 ></P
  94 ><P
  95 ><CODE
  96 ><CODE
  97 CLASS="FUNCDEF"
  98 >void
  99 lwres_sethostent</CODE
 100 >(int stayopen);</CODE
 101 ></P
 102 ><P
 103 ><CODE
 104 ><CODE
 105 CLASS="FUNCDEF"
 106 >void
 107 lwres_endhostent</CODE
 108 >(void);</CODE
 109 ></P
 110 ><P
 111 ><CODE
 112 ><CODE
 113 CLASS="FUNCDEF"
 114 >struct hostent *
 115 lwres_gethostbyname_r</CODE
 116 >(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
 117 ></P
 118 ><P
 119 ><CODE
 120 ><CODE
 121 CLASS="FUNCDEF"
 122 >struct hostent  *
 123 lwres_gethostbyaddr_r</CODE
 124 >(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
 125 ></P
 126 ><P
 127 ><CODE
 128 ><CODE
 129 CLASS="FUNCDEF"
 130 >struct hostent  *
 131 lwres_gethostent_r</CODE
 132 >(struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
 133 ></P
 134 ><P
 135 ><CODE
 136 ><CODE
 137 CLASS="FUNCDEF"
 138 >void
 139 lwres_sethostent_r</CODE
 140 >(int stayopen);</CODE
 141 ></P
 142 ><P
 143 ><CODE
 144 ><CODE
 145 CLASS="FUNCDEF"
 146 >void
 147 lwres_endhostent_r</CODE
 148 >(void);</CODE
 149 ></P
 150 ><P
 151 ></P
 152 ></DIV
 153 ></DIV
 154 ><DIV
 155 CLASS="REFSECT1"
 156 ><A
 157 NAME="AEN84"
 158 ></A
 159 ><H2
 160 >DESCRIPTION</H2
 161 ><P
 162 >These functions provide hostname-to-address and
 163 address-to-hostname lookups by means of the lightweight resolver.
 164 They are similar to the standard
 165 <SPAN
 166 CLASS="CITEREFENTRY"
 167 ><SPAN
 168 CLASS="REFENTRYTITLE"
 169 >gethostent</SPAN
 170 >(3)</SPAN
 171 >
 172 functions provided by most operating systems.
 173 They use a
 174 <SPAN
 175 CLASS="TYPE"
 176 >struct hostent</SPAN
 177 >
 178 which is usually defined in
 179 <TT
 180 CLASS="FILENAME"
 181 >&lt;namedb.h&gt;</TT
 182 >.
 183
 184 <PRE
 185 CLASS="PROGRAMLISTING"
 186 >struct  hostent {
 187         char    *h_name;        /* official name of host */
 188         char    **h_aliases;    /* alias list */
 189         int     h_addrtype;     /* host address type */
 190         int     h_length;       /* length of address */
 191         char    **h_addr_list;  /* list of addresses from name server */
 192 };
 193 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */</PRE
 194 ></P
 195 ><P
 196 >The members of this structure are:
 197 <P
 198 ></P
 199 ><DIV
 200 CLASS="VARIABLELIST"
 201 ><DL
 202 ><DT
 203 ><TT
 204 CLASS="CONSTANT"
 205 >h_name</TT
 206 ></DT
 207 ><DD
 208 ><P
 209 >The official (canonical) name of the host.</P
 210 ></DD
 211 ><DT
 212 ><TT
 213 CLASS="CONSTANT"
 214 >h_aliases</TT
 215 ></DT
 216 ><DD
 217 ><P
 218 >A NULL-terminated array of alternate names (nicknames) for the host.</P
 219 ></DD
 220 ><DT
 221 ><TT
 222 CLASS="CONSTANT"
 223 >h_addrtype</TT
 224 ></DT
 225 ><DD
 226 ><P
 227 >The type of address being returned &mdash;
 228 <SPAN
 229 CLASS="TYPE"
 230 >PF_INET</SPAN
 231 >
 232 or
 233 <SPAN
 234 CLASS="TYPE"
 235 >PF_INET6</SPAN
 236 >.</P
 237 ></DD
 238 ><DT
 239 ><TT
 240 CLASS="CONSTANT"
 241 >h_length</TT
 242 ></DT
 243 ><DD
 244 ><P
 245 >The length of the address in bytes.</P
 246 ></DD
 247 ><DT
 248 ><TT
 249 CLASS="CONSTANT"
 250 >h_addr_list</TT
 251 ></DT
 252 ><DD
 253 ><P
 254 >A <SPAN
 255 CLASS="TYPE"
 256 >NULL</SPAN
 257 >
 258 terminated array of network addresses for the host.
 259 Host addresses are returned in network byte order.</P
 260 ></DD
 261 ></DL
 262 ></DIV
 263 ></P
 264 ><P
 265 >For backward compatibility with very old software,
 266 <TT
 267 CLASS="CONSTANT"
 268 >h_addr</TT
 269 >
 270 is the first address in
 271 <TT
 272 CLASS="CONSTANT"
 273 >h_addr_list.</TT
 274 ></P
 275 ><P
 276 ><TT
 277 CLASS="FUNCTION"
 278 >lwres_gethostent()</TT
 279 >,
 280 <TT
 281 CLASS="FUNCTION"
 282 >lwres_sethostent()</TT
 283 >,
 284 <TT
 285 CLASS="FUNCTION"
 286 >lwres_endhostent()</TT
 287 >,
 288 <TT
 289 CLASS="FUNCTION"
 290 >lwres_gethostent_r()</TT
 291 >,
 292 <TT
 293 CLASS="FUNCTION"
 294 >lwres_sethostent_r()</TT
 295 >
 296 and
 297 <TT
 298 CLASS="FUNCTION"
 299 >lwres_endhostent_r()</TT
 300 >
 301 provide iteration over the known host entries on systems that
 302 provide such functionality through facilities like
 303 <TT
 304 CLASS="FILENAME"
 305 >/etc/hosts</TT
 306 >
 307 or NIS.  The lightweight resolver does not currently implement
 308 these functions; it only provides them as stub functions that always
 309 return failure.</P
 310 ><P
 311 ><TT
 312 CLASS="FUNCTION"
 313 >lwres_gethostbyname()</TT
 314 > and
 315 <TT
 316 CLASS="FUNCTION"
 317 >lwres_gethostbyname2()</TT
 318 > look up the hostname
 319 <TT
 320 CLASS="PARAMETER"
 321 ><I
 322 >name</I
 323 ></TT
 324 >.
 325 <TT
 326 CLASS="FUNCTION"
 327 >lwres_gethostbyname()</TT
 328 > always looks for an IPv4
 329 address while <TT
 330 CLASS="FUNCTION"
 331 >lwres_gethostbyname2()</TT
 332 > looks for an
 333 address of protocol family <TT
 334 CLASS="PARAMETER"
 335 ><I
 336 >af</I
 337 ></TT
 338 >: either
 339 <SPAN
 340 CLASS="TYPE"
 341 >PF_INET</SPAN
 342 > or <SPAN
 343 CLASS="TYPE"
 344 >PF_INET6</SPAN
 345 > &mdash; IPv4 or IPV6
 346 addresses respectively.  Successful calls of the functions return a
 347 <SPAN
 348 CLASS="TYPE"
 349 >struct hostent</SPAN
 350 >for the name that was looked up.
 351 <SPAN
 352 CLASS="TYPE"
 353 >NULL</SPAN
 354 > is returned if the lookups by
 355 <TT
 356 CLASS="FUNCTION"
 357 >lwres_gethostbyname()</TT
 358 > or
 359 <TT
 360 CLASS="FUNCTION"
 361 >lwres_gethostbyname2()</TT
 362 > fail.</P
 363 ><P
 364 >Reverse lookups of addresses are performed by
 365 <TT
 366 CLASS="FUNCTION"
 367 >lwres_gethostbyaddr()</TT
 368 >.
 369 <TT
 370 CLASS="PARAMETER"
 371 ><I
 372 >addr</I
 373 ></TT
 374 > is an address of length
 375 <TT
 376 CLASS="PARAMETER"
 377 ><I
 378 >len</I
 379 ></TT
 380 > bytes and protocol family
 381 <TT
 382 CLASS="PARAMETER"
 383 ><I
 384 >type</I
 385 ></TT
 386 > &mdash; <SPAN
 387 CLASS="TYPE"
 388 >PF_INET</SPAN
 389 > or
 390 <SPAN
 391 CLASS="TYPE"
 392 >PF_INET6</SPAN
 393 >.
 394 <TT
 395 CLASS="FUNCTION"
 396 >lwres_gethostbyname_r()</TT
 397 > is a thread-safe function
 398 for forward lookups.  If an error occurs, an error code is returned in
 399 <TT
 400 CLASS="PARAMETER"
 401 ><I
 402 >*error</I
 403 ></TT
 404 >.
 405 <TT
 406 CLASS="PARAMETER"
 407 ><I
 408 >resbuf</I
 409 ></TT
 410 > is a pointer to a <SPAN
 411 CLASS="TYPE"
 412 >struct
 413 hostent</SPAN
 414 > which is initialised by a successful call to
 415 <TT
 416 CLASS="FUNCTION"
 417 >lwres_gethostbyname_r()</TT
 418 > .
 419 <TT
 420 CLASS="PARAMETER"
 421 ><I
 422 >buf</I
 423 ></TT
 424 > is a buffer of length
 425 <TT
 426 CLASS="PARAMETER"
 427 ><I
 428 >len</I
 429 ></TT
 430 > bytes which is used to store the
 431 <TT
 432 CLASS="CONSTANT"
 433 >h_name</TT
 434 >, <TT
 435 CLASS="CONSTANT"
 436 >h_aliases</TT
 437 >, and
 438 <TT
 439 CLASS="CONSTANT"
 440 >h_addr_list</TT
 441 > elements of the <SPAN
 442 CLASS="TYPE"
 443 >struct
 444 hostent</SPAN
 445 > returned in <TT
 446 CLASS="PARAMETER"
 447 ><I
 448 >resbuf</I
 449 ></TT
 450 >.
 451 Successful calls to <TT
 452 CLASS="FUNCTION"
 453 >lwres_gethostbyname_r()</TT
 454 >
 455 return <TT
 456 CLASS="PARAMETER"
 457 ><I
 458 >resbuf</I
 459 ></TT
 460 >,
 461 which is a pointer to the <SPAN
 462 CLASS="TYPE"
 463 >struct hostent</SPAN
 464 > it created.</P
 465 ><P
 466 ><TT
 467 CLASS="FUNCTION"
 468 >lwres_gethostbyaddr_r()</TT
 469 > is a thread-safe function
 470 that performs a reverse lookup of address <TT
 471 CLASS="PARAMETER"
 472 ><I
 473 >addr</I
 474 ></TT
 475 >
 476 which is <TT
 477 CLASS="PARAMETER"
 478 ><I
 479 >len</I
 480 ></TT
 481 > bytes long and is of protocol
 482 family <TT
 483 CLASS="PARAMETER"
 484 ><I
 485 >type</I
 486 ></TT
 487 > &mdash; <SPAN
 488 CLASS="TYPE"
 489 >PF_INET</SPAN
 490 > or
 491 <SPAN
 492 CLASS="TYPE"
 493 >PF_INET6</SPAN
 494 >.  If an error occurs, the error code is returned
 495 in <TT
 496 CLASS="PARAMETER"
 497 ><I
 498 >*error</I
 499 ></TT
 500 >.  The other function parameters are
 501 identical to those in <TT
 502 CLASS="FUNCTION"
 503 >lwres_gethostbyname_r()</TT
 504 >.
 505 <TT
 506 CLASS="PARAMETER"
 507 ><I
 508 >resbuf</I
 509 ></TT
 510 > is a pointer to a <SPAN
 511 CLASS="TYPE"
 512 >struct
 513 hostent</SPAN
 514 > which is initialised by a successful call to
 515 <TT
 516 CLASS="FUNCTION"
 517 >lwres_gethostbyaddr_r()</TT
 518 >.
 519 <TT
 520 CLASS="PARAMETER"
 521 ><I
 522 >buf</I
 523 ></TT
 524 > is a buffer of length
 525 <TT
 526 CLASS="PARAMETER"
 527 ><I
 528 >len</I
 529 ></TT
 530 > bytes which is used to store the
 531 <TT
 532 CLASS="CONSTANT"
 533 >h_name</TT
 534 >, <TT
 535 CLASS="CONSTANT"
 536 >h_aliases</TT
 537 >, and
 538 <TT
 539 CLASS="CONSTANT"
 540 >h_addr_list</TT
 541 > elements of the <SPAN
 542 CLASS="TYPE"
 543 >struct
 544 hostent</SPAN
 545 > returned in <TT
 546 CLASS="PARAMETER"
 547 ><I
 548 >resbuf</I
 549 ></TT
 550 >.  Successful
 551 calls to <TT
 552 CLASS="FUNCTION"
 553 >lwres_gethostbyaddr_r()</TT
 554 > return
 555 <TT
 556 CLASS="PARAMETER"
 557 ><I
 558 >resbuf</I
 559 ></TT
 560 >, which is a pointer to the
 561 <TT
 562 CLASS="FUNCTION"
 563 >struct hostent()</TT
 564 > it created.</P
 565 ></DIV
 566 ><DIV
 567 CLASS="REFSECT1"
 568 ><A
 569 NAME="AEN191"
 570 ></A
 571 ><H2
 572 >RETURN VALUES</H2
 573 ><P
 574 >The functions
 575 <TT
 576 CLASS="FUNCTION"
 577 >lwres_gethostbyname()</TT
 578 >,
 579 <TT
 580 CLASS="FUNCTION"
 581 >lwres_gethostbyname2()</TT
 582 >,
 583 <TT
 584 CLASS="FUNCTION"
 585 >lwres_gethostbyaddr()</TT
 586 >,
 587 and
 588 <TT
 589 CLASS="FUNCTION"
 590 >lwres_gethostent()</TT
 591 >
 592 return NULL to indicate an error.  In this case the global variable
 593 <SPAN
 594 CLASS="TYPE"
 595 >lwres_h_errno</SPAN
 596 >
 597 will contain one of the following error codes defined in
 598 <TT
 599 CLASS="FILENAME"
 600 >&lt;lwres/netdb.h&gt;</TT
 601 >:
 602
 603 <P
 604 ></P
 605 ><DIV
 606 CLASS="VARIABLELIST"
 607 ><DL
 608 ><DT
 609 ><TT
 610 CLASS="CONSTANT"
 611 >HOST_NOT_FOUND</TT
 612 ></DT
 613 ><DD
 614 ><P
 615 >The host or address was not found.</P
 616 ></DD
 617 ><DT
 618 ><TT
 619 CLASS="CONSTANT"
 620 >TRY_AGAIN</TT
 621 ></DT
 622 ><DD
 623 ><P
 624 >A recoverable error occurred, e.g., a timeout.
 625 Retrying the lookup may succeed.</P
 626 ></DD
 627 ><DT
 628 ><TT
 629 CLASS="CONSTANT"
 630 >NO_RECOVERY</TT
 631 ></DT
 632 ><DD
 633 ><P
 634 >A non-recoverable error occurred.</P
 635 ></DD
 636 ><DT
 637 ><TT
 638 CLASS="CONSTANT"
 639 >NO_DATA</TT
 640 ></DT
 641 ><DD
 642 ><P
 643 >The name exists, but has no address information
 644 associated with it (or vice versa in the case
 645 of a reverse lookup).  The code NO_ADDRESS
 646 is accepted as a synonym for NO_DATA for backwards
 647 compatibility.</P
 648 ></DD
 649 ></DL
 650 ></DIV
 651 ></P
 652 ><P
 653 ><SPAN
 654 CLASS="CITEREFENTRY"
 655 ><SPAN
 656 CLASS="REFENTRYTITLE"
 657 >lwres_hstrerror</SPAN
 658 >(3)</SPAN
 659 >
 660 translates these error codes to suitable error messages.</P
 661 ><P
 662 ><TT
 663 CLASS="FUNCTION"
 664 >lwres_gethostent()</TT
 665 >
 666 and
 667 <TT
 668 CLASS="FUNCTION"
 669 >lwres_gethostent_r()</TT
 670 >
 671 always return
 672 <SPAN
 673 CLASS="TYPE"
 674 >NULL</SPAN
 675 >.</P
 676 ><P
 677 >Successful calls to <TT
 678 CLASS="FUNCTION"
 679 >lwres_gethostbyname_r()</TT
 680 > and
 681 <TT
 682 CLASS="FUNCTION"
 683 >lwres_gethostbyaddr_r()</TT
 684 > return
 685 <TT
 686 CLASS="PARAMETER"
 687 ><I
 688 >resbuf</I
 689 ></TT
 690 >, a pointer to the <SPAN
 691 CLASS="TYPE"
 692 >struct
 693 hostent</SPAN
 694 > that was initialised by these functions.  They return
 695 <SPAN
 696 CLASS="TYPE"
 697 >NULL</SPAN
 698 > if the lookups fail or if <TT
 699 CLASS="PARAMETER"
 700 ><I
 701 >buf</I
 702 ></TT
 703 >
 704 was too small to hold the list of addresses and names referenced by
 705 the <TT
 706 CLASS="CONSTANT"
 707 >h_name</TT
 708 >, <TT
 709 CLASS="CONSTANT"
 710 >h_aliases</TT
 711 >, and
 712 <TT
 713 CLASS="CONSTANT"
 714 >h_addr_list</TT
 715 > elements of the <SPAN
 716 CLASS="TYPE"
 717 >struct
 718 hostent</SPAN
 719 >.  If <TT
 720 CLASS="PARAMETER"
 721 ><I
 722 >buf</I
 723 ></TT
 724 > was too small, both
 725 <TT
 726 CLASS="FUNCTION"
 727 >lwres_gethostbyname_r()</TT
 728 > and
 729 <TT
 730 CLASS="FUNCTION"
 731 >lwres_gethostbyaddr_r()</TT
 732 > set the global variable
 733 <SPAN
 734 CLASS="TYPE"
 735 >errno</SPAN
 736 > to <SPAN
 737 CLASS="ERRORCODE"
 738 >ERANGE</SPAN
 739 >.</P
 740 ></DIV
 741 ><DIV
 742 CLASS="REFSECT1"
 743 ><A
 744 NAME="AEN245"
 745 ></A
 746 ><H2
 747 >SEE ALSO</H2
 748 ><P
 749 ><SPAN
 750 CLASS="CITEREFENTRY"
 751 ><SPAN
 752 CLASS="REFENTRYTITLE"
 753 >gethostent</SPAN
 754 >(3)</SPAN
 755 >,
 756
 757 <SPAN
 758 CLASS="CITEREFENTRY"
 759 ><SPAN
 760 CLASS="REFENTRYTITLE"
 761 >lwres_getipnode</SPAN
 762 >(3)</SPAN
 763 >,
 764
 765 <SPAN
 766 CLASS="CITEREFENTRY"
 767 ><SPAN
 768 CLASS="REFENTRYTITLE"
 769 >lwres_hstrerror</SPAN
 770 >(3)</SPAN
 771 ></P
 772 ></DIV
 773 ><DIV
 774 CLASS="REFSECT1"
 775 ><A
 776 NAME="AEN257"
 777 ></A
 778 ><H2
 779 >BUGS</H2
 780 ><P
 781 ><TT
 782 CLASS="FUNCTION"
 783 >lwres_gethostbyname()</TT
 784 >,
 785 <TT
 786 CLASS="FUNCTION"
 787 >lwres_gethostbyname2()</TT
 788 >,
 789 <TT
 790 CLASS="FUNCTION"
 791 >lwres_gethostbyaddr()</TT
 792 >
 793 and
 794 <TT
 795 CLASS="FUNCTION"
 796 >lwres_endhostent()</TT
 797 >
 798 are not thread safe; they return pointers to static data and
 799 provide error codes through a global variable.
 800 Thread-safe versions for name and address lookup are provided by
 801 <TT
 802 CLASS="FUNCTION"
 803 >lwres_gethostbyname_r()</TT
 804 >,
 805 and
 806 <TT
 807 CLASS="FUNCTION"
 808 >lwres_gethostbyaddr_r()</TT
 809 >
 810 respectively.</P
 811 ><P
 812 >The resolver daemon does not currently support any non-DNS
 813 name services such as
 814 <TT
 815 CLASS="FILENAME"
 816 >/etc/hosts</TT
 817 >
 818 or
 819 <SPAN
 820 CLASS="TYPE"
 821 >NIS</SPAN
 822 >,
 823 consequently the above functions don't, either.</P
 824 ></DIV
 825 ></BODY
 826 ></HTML
 827 >