doc/html/ref/net-common-tcpip-manpages-gethostbyname.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >gethostbyname</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="getaddrinfo"
  26 HREF="net-common-tcpip-manpages-getaddrinfo.html"><LINK
  27 REL="NEXT"
  28 TITLE="getifaddrs"
  29 HREF="net-common-tcpip-manpages-getifaddrs.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-getaddrinfo.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-getifaddrs.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-GETHOSTBYNAME">gethostbyname</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >GETHOSTBYNAME(3)        System Library Functions Manual       GETHOSTBYNAME(3)
  95
  96 NAME
  97      gethostbyname, gethostbyname2, gethostbyaddr, gethostent, sethostent,
  98      endhostent, hstrerror, herror - get network host entry
  99
 100 SYNOPSIS
 101      #include &lt;netdb.h&#62;
 102      extern int h_errno;
 103
 104      struct hostent *
 105      gethostbyname(const char *name);
 106
 107      struct hostent *
 108      gethostbyname2(const char *name, int af);
 109
 110      struct hostent *
 111      gethostbyaddr(const char *addr, int len, int af);
 112
 113      struct hostent *
 114      gethostent(void);
 115
 116      void
 117      sethostent(int stayopen);
 118
 119      void
 120      endhostent(void);
 121
 122      void
 123      herror(const char *string);
 124
 125      const char *
 126      hstrerror(int err);
 127
 128 DESCRIPTION
 129      The gethostbyname() and gethostbyaddr() functions each return a pointer
 130      to an object with the following structure describing an internet host
 131      referenced by name or by address, respectively.  This structure contains
 132      either information obtained from the name server (i.e., resolver(3) and
 133      named(8)), broken-out fields from a line in /etc/hosts, or database
 134      entries supplied by the yp(8) system.  resolv.conf(5) describes how the
 135      particular database is chosen.
 136
 137      struct  hostent {
 138              char    *h_name;        /* official name of host */
 139              char    **h_aliases;    /* alias list */
 140              int     h_addrtype;     /* host address type */
 141              int     h_length;       /* length of address */
 142              char    **h_addr_list;  /* list of addresses from name server */
 143      };
 144      #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 145
 146      The members of this structure are:
 147
 148      h_name       Official name of the host.
 149
 150      h_aliases    A zero-terminated array of alternate names for the host.
 151
 152      h_addrtype   The type of address being returned.
 153
 154      h_length     The length, in bytes, of the address.
 155
 156      h_addr_list  A zero-terminated array of network addresses for the host.
 157                   Host addresses are returned in network byte order.
 158
 159      h_addr       The first address in h_addr_list; this is for backward com-
 160                   patibility.
 161
 162      The function gethostbyname() will search for the named host in the cur-
 163      rent domain and its parents using the search lookup semantics detailed in
 164      resolv.conf(5) and hostname(7).
 165
 166      gethostbyname2() is an advanced form of gethostbyname() which allows
 167      lookups in address families other than AF_INET, for example AF_INET6.
 168
 169      The gethostbyaddr() function will search for the specified address of
 170      length len in the address family af.  The only address family currently
 171      supported is AF_INET.
 172
 173      The sethostent() function may be used to request the use of a connected
 174      TCP socket for queries.  If the stayopen flag is non-zero, this sets the
 175      option to send all queries to the name server using TCP and to retain the
 176      connection after each call to gethostbyname() or gethostbyaddr().  Other-
 177      wise, queries are performed using UDP datagrams.
 178
 179      The endhostent() function closes the TCP connection.
 180
 181      The herror() function prints an error message describing the failure.  If
 182      its argument string is non-null, it is prepended to the message string
 183      and separated from it by a colon (`:') and a space.  The error message is
 184      printed with a trailing newline.  The contents of the error message is
 185      the same as that returned by hstrerror() with argument h_errno.
 186
 187 FILES
 188      /etc/hosts
 189      /etc/resolv.conf
 190
 191 DIAGNOSTICS
 192      Error return status from gethostbyname(), gethostbyname2(), and
 193      gethostbyaddr() is indicated by return of a null pointer.  The external
 194      integer h_errno may then be checked to see whether this is a temporary
 195      failure or an invalid or unknown host.
 196
 197      The variable h_errno can have the following values:
 198
 199      HOST_NOT_FOUND  No such host is known.
 200
 201      TRY_AGAIN       This is usually a temporary error and means that the
 202                      local server did not receive a response from an authori-
 203                      tative server.  A retry at some later time may succeed.
 204
 205      NO_RECOVERY     Some unexpected server failure was encountered.  This is
 206                      a non-recoverable error.
 207
 208      NO_DATA         The requested name is valid but does not have an IP
 209                      address; this is not a temporary error.  This means that
 210                      the name is known to the name server but there is no
 211                      address associated with this name.  Another type of
 212                      request to the name server using this domain name will
 213                      result in an answer; for example, a mail-forwarder may be
 214                      registered for this domain.
 215
 216 SEE ALSO
 217      resolver(3), getaddrinfo(3), getnameinfo(3), hosts(5), resolv.conf(5),
 218      hostname(7), named(8)
 219
 220 CAVEAT
 221      If the search routines in resolv.conf(5) decide to read the /etc/hosts
 222      file, gethostent() and other functions will read the next line of the
 223      file, re-opening the file if necessary.
 224
 225      The sethostent() function opens and/or rewinds the file /etc/hosts.  If
 226      the stayopen argument is non-zero, the file will not be closed after each
 227      call to gethostbyname(), gethostbyname2(), or gethostbyaddr().
 228
 229      The endhostent() function closes the file.
 230
 231 HISTORY
 232      The herror() function appeared in 4.3BSD.  The endhostent(),
 233      gethostbyaddr(), gethostbyname(), gethostent(), and sethostent() func-
 234      tions appeared in 4.2BSD.
 235
 236 BUGS
 237      These functions use static data storage; if the data is needed for future
 238      use, it should be copied before any subsequent calls overwrite it.  Only
 239      the Internet address formats are currently understood.
 240
 241      YP does not support any address families other than AF_INET and uses the
 242      traditional database format.
 243
 244 BSD                             March 13, 1997                             BSD
 245     </PRE
 246 ></TD
 247 ></TR
 248 ></TABLE
 249 ></DIV
 250 ><DIV
 251 CLASS="NAVFOOTER"
 252 ><HR
 253 ALIGN="LEFT"
 254 WIDTH="100%"><TABLE
 255 SUMMARY="Footer navigation table"
 256 WIDTH="100%"
 257 BORDER="0"
 258 CELLPADDING="0"
 259 CELLSPACING="0"
 260 ><TR
 261 ><TD
 262 WIDTH="33%"
 263 ALIGN="left"
 264 VALIGN="top"
 265 ><A
 266 HREF="net-common-tcpip-manpages-getaddrinfo.html"
 267 ACCESSKEY="P"
 268 >Prev</A
 269 ></TD
 270 ><TD
 271 WIDTH="34%"
 272 ALIGN="center"
 273 VALIGN="top"
 274 ><A
 275 HREF="ecos-ref.html"
 276 ACCESSKEY="H"
 277 >Home</A
 278 ></TD
 279 ><TD
 280 WIDTH="33%"
 281 ALIGN="right"
 282 VALIGN="top"
 283 ><A
 284 HREF="net-common-tcpip-manpages-getifaddrs.html"
 285 ACCESSKEY="N"
 286 >Next</A
 287 ></TD
 288 ></TR
 289 ><TR
 290 ><TD
 291 WIDTH="33%"
 292 ALIGN="left"
 293 VALIGN="top"
 294 >getaddrinfo</TD
 295 ><TD
 296 WIDTH="34%"
 297 ALIGN="center"
 298 VALIGN="top"
 299 ><A
 300 HREF="tcpip-library-reference.html"
 301 ACCESSKEY="U"
 302 >Up</A
 303 ></TD
 304 ><TD
 305 WIDTH="33%"
 306 ALIGN="right"
 307 VALIGN="top"
 308 >getifaddrs</TD
 309 ></TR
 310 ></TABLE
 311 ></DIV
 312 ></BODY
 313 ></HTML
 314 >