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: src/lib/libc/net/gethostbyname.3,v 1.12.2.7 2001/12/14 18:33:55 ru Exp $
  34 .\" $DragonFly: src/lib/libc/net/gethostbyname.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
  35 .\"
  36 .Dd May 25, 1995
  37 .Dt GETHOSTBYNAME 3
  38 .Os
  39 .Sh NAME
  40 .Nm gethostbyname ,
  41 .Nm gethostbyname2 ,
  42 .Nm gethostbyaddr ,
  43 .Nm gethostent ,
  44 .Nm sethostent ,
  45 .Nm endhostent ,
  46 .Nm herror ,
  47 .Nm hstrerror
  48 .Nd get network host entry
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In netdb.h
  53 .Vt extern int h_errno ;
  54 .Ft struct hostent *
  55 .Fn gethostbyname "const char *name"
  56 .Ft struct hostent *
  57 .Fn gethostbyname2 "const char *name" "int af"
  58 .Ft struct hostent *
  59 .Fn gethostbyaddr "const char *addr" "int len" "int type"
  60 .Ft struct hostent *
  61 .Fn gethostent void
  62 .Ft void
  63 .Fn sethostent "int stayopen"
  64 .Ft void
  65 .Fn endhostent void
  66 .Ft void
  67 .Fn herror "const char *string"
  68 .Ft const char *
  69 .Fn hstrerror "int err"
  70 .Sh DESCRIPTION
  71 The
  72 .Fn gethostbyname ,
  73 .Fn gethostbyname2
  74 and
  75 .Fn gethostbyaddr
  76 functions
  77 each return a pointer to an object with the
  78 following structure describing an internet host
  79 referenced by name or by address, respectively.
  80 This structure contains either the information obtained from the name server,
  81 .Xr named 8 ,
  82 or broken-out fields from a line in
  83 .Pa /etc/hosts .
  84 If the local name server is not running these routines do a lookup in
  85 .Pa /etc/hosts .
  86 .Bd -literal
  87 struct  hostent {
  88         char    *h_name;        /* official name of host */
  89         char    **h_aliases;    /* alias list */
  90         int     h_addrtype;     /* host address type */
  91         int     h_length;       /* length of address */
  92         char    **h_addr_list;  /* list of addresses from name server */
  93 };
  94 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
  95 .Ed
  96 .Pp
  97 The members of this structure are:
  98 .Bl -tag -width h_addr_list
  99 .It Va h_name
 100 Official name of the host.
 101 .It Va h_aliases
 102 A
 103 .Dv NULL Ns -terminated
 104 array of alternate names for the host.
 105 .It Va h_addrtype
 106 The type of address being returned; usually
 107 .Dv AF_INET .
 108 .It Va h_length
 109 The length, in bytes, of the address.
 110 .It Va h_addr_list
 111 A
 112 .Dv NULL Ns -terminated
 113 array of network addresses for the host.
 114 Host addresses are returned in network byte order.
 115 .It Va h_addr
 116 The first address in
 117 .Va h_addr_list ;
 118 this is for backward compatibility.
 119 .El
 120 .Pp
 121 When using the nameserver,
 122 .Fn gethostbyname
 123 and
 124 .Fn gethostbyname2
 125 will search for the named host in the current domain and its parents
 126 unless the name ends in a dot.
 127 If the name contains no dot, and if the environment variable
 128 .Dq Ev HOSTALIASES
 129 contains the name of an alias file, the alias file will first be searched
 130 for an alias matching the input name.
 131 See
 132 .Xr hostname 7
 133 for the domain search procedure and the alias file format.
 134 .Pp
 135 The
 136 .Fn gethostbyname2
 137 function is an evolution of
 138 .Fn gethostbyname
 139 which is intended to allow lookups in address families other than
 140 .Dv AF_INET ,
 141 for example
 142 .Dv AF_INET6 .
 143 Currently the
 144 .Fa af
 145 argument must be specified as
 146 .Dv AF_INET
 147 else the function will return
 148 .Dv NULL
 149 after having set
 150 .Va h_errno
 151 to
 152 .Dv NETDB_INTERNAL
 153 .Pp
 154 The
 155 .Fn sethostent
 156 function
 157 may be used to request the use of a connected
 158 .Tn TCP
 159 socket for queries.
 160 If the
 161 .Fa stayopen
 162 flag is non-zero,
 163 this sets the option to send all queries to the name server using
 164 .Tn TCP
 165 and to retain the connection after each call to
 166 .Fn gethostbyname ,
 167 .Fn gethostbyname2
 168 or
 169 .Fn gethostbyaddr .
 170 Otherwise, queries are performed using
 171 .Tn UDP
 172 datagrams.
 173 .Pp
 174 The
 175 .Fn endhostent
 176 function
 177 closes the
 178 .Tn TCP
 179 connection.
 180 .Pp
 181 The
 182 .Fn herror
 183 function writes a message to the diagnostic output consisting of the
 184 string parameter
 185 .Fa s ,
 186 the constant string
 187 .Qq Li ":\ " ,
 188 and a message corresponding to the value of
 189 .Va h_errno .
 190 .Pp
 191 The
 192 .Fn hstrerror
 193 function returns a string which is the message text corresponding to the
 194 value of the
 195 .Fa err
 196 parameter.
 197 .Sh FILES
 198 .Bl -tag -width /etc/resolv.conf -compact
 199 .It Pa /etc/hosts
 200 .It Pa /etc/host.conf
 201 .It Pa /etc/resolv.conf
 202 .El
 203 .Sh DIAGNOSTICS
 204 Error return status from
 205 .Fn gethostbyname ,
 206 .Fn gethostbyname2
 207 and
 208 .Fn gethostbyaddr
 209 is indicated by return of a
 210 .Dv NULL
 211 pointer.
 212 The external integer
 213 .Va h_errno
 214 may then be checked to see whether this is a temporary failure
 215 or an invalid or unknown host.
 216 The routine
 217 .Fn herror
 218 can be used to print an error message describing the failure.
 219 If its argument
 220 .Fa string
 221 is
 222 .Pf non- Dv NULL ,
 223 it is printed, followed by a colon and a space.
 224 The error message is printed with a trailing newline.
 225 .Pp
 226 The variable
 227 .Va h_errno
 228 can have the following values:
 229 .Bl -tag -width HOST_NOT_FOUND
 230 .It Dv HOST_NOT_FOUND
 231 No such host is known.
 232 .It Dv TRY_AGAIN
 233 This is usually a temporary error
 234 and means that the local server did not receive
 235 a response from an authoritative server.
 236 A retry at some later time may succeed.
 237 .It Dv NO_RECOVERY
 238 Some unexpected server failure was encountered.
 239 This is a non-recoverable error.
 240 .It Dv NO_DATA
 241 The requested name is valid but does not have an IP address;
 242 this is not a temporary error.
 243 This means that the name is known to the name server but there is no address
 244 associated with this name.
 245 Another type of request to the name server using this domain name
 246 will result in an answer;
 247 for example, a mail-forwarder may be registered for this domain.
 248 .El
 249 .Sh SEE ALSO
 250 .Xr getaddrinfo 3 ,
 251 .Xr resolver 3 ,
 252 .Xr hosts 5 ,
 253 .Xr hostname 7 ,
 254 .Xr named 8
 255 .Sh CAVEAT
 256 The
 257 .Fn gethostent
 258 function
 259 is defined, and
 260 .Fn sethostent
 261 and
 262 .Fn endhostent
 263 are redefined,
 264 when
 265 .Xr libc 3
 266 is built to use only the routines to lookup in
 267 .Pa /etc/hosts
 268 and not the name server.
 269 .Pp
 270 The
 271 .Fn gethostent
 272 function
 273 reads the next line of
 274 .Pa /etc/hosts ,
 275 opening the file if necessary.
 276 .Pp
 277 The
 278 .Fn sethostent
 279 function
 280 opens and/or rewinds the file
 281 .Pa /etc/hosts .
 282 If the
 283 .Fa stayopen
 284 argument is non-zero,
 285 the file will not be closed after each call to
 286 .Fn gethostbyname ,
 287 .Fn gethostbyname2
 288 or
 289 .Fn gethostbyaddr .
 290 .Pp
 291 The
 292 .Fn endhostent
 293 function
 294 closes the file.
 295 .Sh HISTORY
 296 The
 297 .Fn herror
 298 function appeared in
 299 .Bx 4.3 .
 300 The
 301 .Fn endhostent ,
 302 .Fn gethostbyaddr ,
 303 .Fn gethostbyname ,
 304 .Fn gethostent ,
 305 and
 306 .Fn sethostent
 307 functions appeared in
 308 .Bx 4.2 .
 309 The
 310 .Fn gethostbyname2
 311 function first appeared in
 312 .Tn BIND
 313 version 4.9.4.
 314 .Sh BUGS
 315 These functions use static data storage;
 316 if the data is needed for future use, it should be
 317 copied before any subsequent calls overwrite it.
 318 Only the Internet
 319 address format is currently understood.