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