lib/libc/net/gethostbyname.3

   1 .\" Copyright (c) 1983, 1987, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd May 25, 1995
  36 .Dt GETHOSTBYNAME 3
  37 .Os BSD 4.2
  38 .Sh NAME
  39 .Nm gethostbyname ,
  40 .Nm gethostbyname2 ,
  41 .Nm gethostbyaddr ,
  42 .Nm gethostent ,
  43 .Nm sethostent ,
  44 .Nm endhostent ,
  45 .Nm herror ,
  46 .Nm hstrerror
  47 .Nd get network host entry
  48 .Sh SYNOPSIS
  49 .Fd #include <netdb.h>
  50 .Vt extern int h_errno;
  51 .Ft struct hostent *
  52 .Fn gethostbyname "const char *name"
  53 .Ft struct hostent *
  54 .Fn gethostbyname2 "const char *name" "int af"
  55 .Ft struct hostent *
  56 .Fn gethostbyaddr "const char *addr" "int len" "int type"
  57 .Ft struct hostent *
  58 .Fn gethostent void
  59 .Ft void
  60 .Fn sethostent "int stayopen"
  61 .Ft void
  62 .Fn endhostent void
  63 .Ft void
  64 .Fn herror "const char *string"
  65 .Ft const char *
  66 .Fn hstrerror "int err"
  67 .Sh DESCRIPTION
  68 The
  69 .Fn gethostbyname ,
  70 .Fn gethostbyname2
  71 and
  72 .Fn gethostbyaddr
  73 functions
  74 each return a pointer to an object with the
  75 following structure describing an internet host
  76 referenced by name or by address, respectively.
  77 This structure contains either the information obtained from the name server,
  78 .Xr named 8 ,
  79 or broken-out fields from a line in
  80 .Pa /etc/hosts .
  81 If the local name server is not running these routines do a lookup in
  82 .Pa /etc/hosts .
  83 .Bd -literal
  84 struct  hostent {
  85         char    *h_name;        /* official name of host */
  86         char    **h_aliases;    /* alias list */
  87         int     h_addrtype;     /* host address type */
  88         int     h_length;       /* length of address */
  89         char    **h_addr_list;  /* list of addresses from name server */
  90 };
  91 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
  92 .Ed
  93 .Pp
  94 The members of this structure are:
  95 .Bl -tag -width h_addr_list
  96 .It Fa h_name
  97 Official name of the host.
  98 .It Fa h_aliases
  99 A NULL-terminated array of alternate names for the host.
 100 .It Fa h_addrtype
 101 The type of address being returned; usually
 102 .Dv AF_INET .
 103 .It Fa h_length
 104 The length, in bytes, of the address.
 105 .It Fa h_addr_list
 106 A NULL-terminated array of network addresses for the host.
 107 Host addresses are returned in network byte order.
 108 .It Fa h_addr
 109 The first address in
 110 .Fa h_addr_list ;
 111 this is for backward compatibility.
 112 .El
 113 .Pp
 114 When using the nameserver,
 115 .Fn gethostbyname
 116 and
 117 .Fn gethostbyname2
 118 will search for the named host in the current domain and its parents
 119 unless the name ends in a dot.
 120 If the name contains no dot, and if the environment variable
 121 .Dq Ev HOSTALIASES
 122 contains the name of an alias file, the alias file will first be searched
 123 for an alias matching the input name.
 124 See
 125 .Xr hostname 7
 126 for the domain search procedure and the alias file format.
 127 .Pp
 128 The
 129 .Fn gethostbyname2
 130 function is an evolution of
 131 .Fn gethostbyname
 132 which is intended to allow lookups in address families other than
 133 .Dv AF_INET ,
 134 for example
 135 .Dv AF_INET6 .
 136 Currently the
 137 .Fa af
 138 argument must be specified as
 139 .Dv AF_INET
 140 else the function will return
 141 .Dv NULL
 142 after having set
 143 .Va h_errno
 144 to
 145 .Dv NETDB_INTERNAL
 146 .Pp
 147 The
 148 .Fn sethostent
 149 function
 150 may be used to request the use of a connected
 151 .Tn TCP
 152 socket for queries.
 153 If the
 154 .Fa stayopen
 155 flag is non-zero,
 156 this sets the option to send all queries to the name server using
 157 .Tn TCP
 158 and to retain the connection after each call to
 159 .Fn gethostbyname ,
 160 .Fn gethostbyname2
 161 or
 162 .Fn gethostbyaddr .
 163 Otherwise, queries are performed using
 164 .Tn UDP
 165 datagrams.
 166 .Pp
 167 The
 168 .Fn endhostent
 169 function
 170 closes the
 171 .Tn TCP
 172 connection.
 173 .Pp
 174 The
 175 .Fn herror
 176 function writes a message to the diagnostic output consisting of the
 177 string parameter
 178 .Fa s ,
 179 the constant string ": ", and a message corresponding to the value of
 180 .Va h_errno .
 181 .Pp
 182 The
 183 .Fn hstrerror
 184 function returns a string which is the message text corresponding to the
 185 value of the
 186 .Fa err
 187 parameter.
 188 .Sh FILES
 189 .Bl -tag -width /etc/resolv.conf -compact
 190 .It Pa /etc/hosts
 191 .It Pa /etc/host.conf
 192 .It Pa /etc/resolv.conf
 193 .El
 194 .Sh DIAGNOSTICS
 195 Error return status from
 196 .Fn gethostbyname ,
 197 .Fn gethostbyname2
 198 and
 199 .Fn gethostbyaddr
 200 is indicated by return of a null pointer.
 201 The external integer
 202 .Va h_errno
 203 may then be checked to see whether this is a temporary failure
 204 or an invalid or unknown host.
 205 The routine
 206 .Fn herror
 207 can be used to print an error message describing the failure.
 208 If its argument
 209 .Fa string
 210 is
 211 .Pf non Dv -NULL ,
 212 it is printed, followed by a colon and a space.
 213 The error message is printed with a trailing newline.
 214 .Pp
 215 The variable
 216 .Va h_errno
 217 can have the following values:
 218 .Bl -tag -width HOST_NOT_FOUND
 219 .It Dv HOST_NOT_FOUND
 220 No such host is known.
 221 .It Dv TRY_AGAIN
 222 This is usually a temporary error
 223 and means that the local server did not receive
 224 a response from an authoritative server.
 225 A retry at some later time may succeed.
 226 .It Dv NO_RECOVERY
 227 Some unexpected server failure was encountered.
 228 This is a non-recoverable error.
 229 .It Dv NO_DATA
 230 The requested name is valid but does not have an IP address;
 231 this is not a temporary error.
 232 This means that the name is known to the name server but there is no address
 233 associated with this name.
 234 Another type of request to the name server using this domain name
 235 will result in an answer;
 236 for example, a mail-forwarder may be registered for this domain.
 237 .El
 238 .Sh SEE ALSO
 239 .Xr resolver 3 ,
 240 .Xr hosts 5 ,
 241 .Xr hostname 7 ,
 242 .Xr named 8
 243 .Sh CAVEAT
 244 The
 245 .Fn gethostent
 246 function
 247 is defined, and
 248 .Fn sethostent
 249 and
 250 .Fn endhostent
 251 are redefined,
 252 when
 253 .Xr libc 3
 254 is built to use only the routines to lookup in
 255 .Pa /etc/hosts
 256 and not the name server.
 257 .Pp
 258 The
 259 .Fn gethostent
 260 function
 261 reads the next line of
 262 .Pa /etc/hosts ,
 263 opening the file if necessary.
 264 .Pp
 265 The
 266 .Fn sethostent
 267 function
 268 opens and/or rewinds the file
 269 .Pa /etc/hosts .
 270 If the
 271 .Fa stayopen
 272 argument is non-zero,
 273 the file will not be closed after each call to
 274 .Fn gethostbyname ,
 275 .Fn gethostbyname2
 276 or
 277 .Fn gethostbyaddr .
 278 .Pp
 279 The
 280 .Fn endhostent
 281 function
 282 closes the file.
 283 .Sh HISTORY
 284 The
 285 .Fn herror
 286 function appeared in
 287 .Bx 4.3 .
 288 The
 289 .Fn endhostent ,
 290 .Fn gethostbyaddr ,
 291 .Fn gethostbyname ,
 292 .Fn gethostent ,
 293 and
 294 .Fn sethostent
 295 functions appeared in
 296 .Bx 4.2 .
 297 The
 298 .Fn gethostbyname2
 299 function first appeared in bind-4.9.4.
 300 .Sh BUGS
 301 These functions use static data storage;
 302 if the data is needed for future use, it should be
 303 copied before any subsequent calls overwrite it.
 304 Only the Internet
 305 address format is currently understood.