external/bsd/libbind/dist/doc/gethostbyname.3

   1 .\"     $NetBSD$
   2 .\"
   3 .\" Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
   4 .\"
   5 .\" Permission to use, copy, modify, and/or 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 .\" Id: gethostbyname.3,v 1.3 2009/01/22 23:49:23 tbox Exp
  18 .\"
  19 .Dd June 23, 1990
  20 .Dt GETHOSTBYNAME @LIB_NETWORK_EXT_U@
  21 .Os BSD 4
  22 .Sh NAME
  23 .Nm gethostbyname ,
  24 .Nm gethostbyaddr ,
  25 .Nm gethostent ,
  26 .Nm sethostent ,
  27 .Nm endhostent ,
  28 .Nm herror
  29 .Nd get network host entry
  30 .Sh SYNOPSIS
  31 .Fd #include <netdb.h>
  32 .Ft extern int
  33 .Fa h_errno ;
  34 .Pp
  35 .Ft struct hostent *
  36 .Fn gethostbyname "char *name"
  37 .Ft struct hostent *
  38 .Fn gethostbyname2 "char *name" "int af"
  39 .Ft struct hostent *
  40 .Fn gethostbyaddr "char *addr" "int len, type"
  41 .Ft struct hostent *
  42 .Fn gethostent
  43 .Fn sethostent "int stayopen"
  44 .Fn endhostent
  45 .Fn herror "char *string"
  46 .Sh DESCRIPTION
  47 .Fn Gethostbyname ,
  48 .Fn gethostbyname2 ,
  49 and
  50 .Fn gethostbyaddr
  51 each return a pointer to a
  52 .Ft hostent
  53 structure (see below) describing an internet host
  54 referenced by name or by address, as the function names indicate.
  55 This structure contains either the information obtained from the name server,
  56 or broken-out fields from a line in
  57 .Pa /etc/hosts .
  58 If the local name server is not running, these routines do a lookup in
  59 .Pa /etc/hosts .
  60 .Bd -literal -offset indent
  61 struct  hostent {
  62         char    *h_name;        /* official name of host */
  63         char    **h_aliases;    /* alias list */
  64         int     h_addrtype;     /* host address type */
  65         int     h_length;       /* length of address */
  66         char    **h_addr_list;  /* list of addresses from name server */
  67 };
  68
  69 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
  70 .Ed
  71 .Pp
  72 The members of this structure are:
  73 .Bl -tag -width "h_addr_list"
  74 .It h_name
  75 Official name of the host.
  76 .It h_aliases
  77 A zero-terminated array of alternate names for the host.
  78 .It h_addrtype
  79 The type of address being returned; usually
  80 .Dv AF_INET .
  81 .It h_length
  82 The length, in bytes, of the address.
  83 .It h_addr_list
  84 A zero-terminated array of network addresses for the host.
  85 Host addresses are returned in network byte order.
  86 .It h_addr
  87 The first address in
  88 .Li h_addr_list ;
  89 this is for backward compatibility.
  90 .El
  91 .Pp
  92 When using the nameserver,
  93 .Fn gethostbyname
  94 will search for the named host in each parent domain given in the
  95 .Dq Li search
  96 directive of
  97 .Xr resolv.conf @FORMAT_EXT@
  98 unless the name contains a dot
  99 .Pq Dq \&. .
 100 If the name contains no dot, and if the environment variable
 101 .Ev HOSTALIASES
 102 contains the name of an alias file, the alias file will first be searched
 103 for an alias matching the input name.
 104 See
 105 .Xr hostname @DESC_EXT@
 106 for the domain search procedure and the alias file format.
 107 .Pp
 108 .Fn Gethostbyname2
 109 is an evolution of
 110 .Fn gethostbyname
 111 intended to allow lookups in address families other than
 112 .Dv AF_INET ,
 113 for example,
 114 .Dv AF_INET6 .
 115 Currently, the
 116 .Fa af
 117 argument must be specified as
 118 .Dv AF_INET
 119 else the function will return
 120 .Dv NULL
 121 after having set
 122 .Ft h_errno
 123 to
 124 .Dv NETDB_INTERNAL .
 125 .Pp
 126 .Fn Sethostent
 127 may be used to request the use of a connected TCP socket for queries.
 128 If the
 129 .Fa stayopen
 130 flag is non-zero,
 131 this sets the option to send all queries to the name server using TCP
 132 and to retain the connection after each call to
 133 .Fn gethostbyname
 134 or
 135 .Fn gethostbyaddr .
 136 Otherwise, queries are performed using UDP datagrams.
 137 .Pp
 138 .Fn Endhostent
 139 closes the TCP connection.
 140 .Sh ENVIRONMENT
 141 .Bl -tag -width "HOSTALIASES  " -compact
 142 .It Ev HOSTALIASES
 143 Name of file containing
 144 .Pq Ar host alias , full hostname
 145 pairs.
 146 .El
 147 .Sh FILES
 148 .Bl -tag -width "HOSTALIASES  " -compact
 149 .It Pa /etc/hosts
 150 See
 151 .Xr hosts @FORMAT_EXT@ .
 152 .El
 153 .Sh DIAGNOSTICS
 154 .Pp
 155 Error return status from
 156 .Fn gethostbyname
 157 and
 158 .Fn gethostbyaddr
 159 is indicated by return of a null pointer.
 160 The external integer
 161 .Ft h_errno
 162 may then be checked to see whether this is a temporary failure
 163 or an invalid or unknown host.
 164 The routine
 165 .Fn herror
 166 can be used to print an error message describing the failure.
 167 If its argument
 168 .Fa string
 169 is non-NULL, it is printed, followed by a colon and a space.
 170 The error message is printed with a trailing newline.
 171 .Pp
 172 .Ft h_errno
 173 can have the following values:
 174 .Bl -tag -width "HOST_NOT_FOUND  " -offset indent
 175 .It Dv NETDB_INTERNAL
 176 This indicates an internal error in the library, unrelated to the network
 177 or name service.
 178 .Ft errno
 179 will be valid in this case; see
 180 .Xr perror @SYSCALL_EXT@ .
 181 .It Dv HOST_NOT_FOUND
 182 No such host is known.
 183 .It Dv TRY_AGAIN
 184 This is usually a temporary error
 185 and means that the local server did not receive
 186 a response from an authoritative server.
 187 A retry at some later time may succeed.
 188 .It Dv NO_RECOVERY
 189 Some unexpected server failure was encountered.
 190 This is a non-recoverable error, as one might expect.
 191 .It Dv NO_DATA
 192 The requested name is valid but does not have an IP address;
 193 this is not a temporary error.
 194 This means that the name is known to the name server but there is no address
 195 associated with this name.
 196 Another type of request to the name server using this domain name
 197 will result in an answer;
 198 for example, a mail-forwarder may be registered for this domain.
 199 .El
 200 .Sh SEE ALSO
 201 .Xr hosts @FORMAT_EXT@ ,
 202 .Xr hostname @DESC_EXT@ ,
 203 .Xr resolver @LIB_NETWORK_EXT@ ,
 204 .Xr resolver @FORMAT_EXT@ .
 205 .Sh CAVEAT
 206 .Pp
 207 .Fn Gethostent
 208 is defined, and
 209 .Fn sethostent
 210 and
 211 .Fn endhostent
 212 are redefined,
 213 when
 214 .Pa libc
 215 is built to use only the routines to lookup in
 216 .Pa /etc/hosts
 217 and not the name server:
 218 .Bd -ragged -offset indent
 219 .Pp
 220 .Fn Gethostent
 221 reads the next line of
 222 .Pa /etc/hosts ,
 223 opening the file if necessary.
 224 .Pp
 225 .Fn Sethostent
 226 is redefined to open and rewind the file.  If the
 227 .Fa stayopen
 228 argument is non-zero,
 229 the hosts data base will not be closed after each call to
 230 .Fn gethostbyname
 231 or
 232 .Fn gethostbyaddr .
 233 .Pp
 234 .Fn Endhostent
 235 is redefined to close the file.
 236 .Ed
 237 .Sh BUGS
 238 All information is contained in a static area so it must be copied if it is
 239 to be saved.  Only the Internet address format is currently understood.