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