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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 12, 2006
  32 .Dt GETHOSTBYNAME 3
  33 .Os
  34 .Sh NAME
  35 .Nm gethostbyname ,
  36 .Nm gethostbyname2 ,
  37 .Nm gethostbyaddr ,
  38 .Nm gethostent ,
  39 .Nm sethostent ,
  40 .Nm endhostent ,
  41 .Nm herror ,
  42 .Nm hstrerror
  43 .Nd get network host entry
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In netdb.h
  48 .Vt int h_errno ;
  49 .Ft struct hostent *
  50 .Fn gethostbyname "const char *name"
  51 .Ft struct hostent *
  52 .Fn gethostbyname2 "const char *name" "int af"
  53 .Ft struct hostent *
  54 .Fn gethostbyaddr "const void *addr" "socklen_t len" "int af"
  55 .Ft struct hostent *
  56 .Fn gethostent void
  57 .Ft void
  58 .Fn sethostent "int stayopen"
  59 .Ft void
  60 .Fn endhostent void
  61 .Ft void
  62 .Fn herror "const char *string"
  63 .Ft const char *
  64 .Fn hstrerror "int err"
  65 .Sh DESCRIPTION
  66 .Bf -symbolic
  67 The
  68 .Xr getaddrinfo 3
  69 and
  70 .Xr getnameinfo 3
  71 functions are preferred over the
  72 .Fn gethostbyname ,
  73 .Fn gethostbyname2 ,
  74 and
  75 .Fn gethostbyaddr
  76 functions.
  77 .Ef
  78 .Pp
  79 The
  80 .Fn gethostbyname ,
  81 .Fn gethostbyname2
  82 and
  83 .Fn gethostbyaddr
  84 functions
  85 each return a pointer to an object with the
  86 following structure describing an internet host
  87 referenced by name or by address, respectively.
  88 .Pp
  89 The
  90 .Fa name
  91 argument passed to
  92 .Fn gethostbyname
  93 or
  94 .Fn gethostbyname2
  95 should point to a
  96 .Dv NUL Ns -terminated
  97 hostname.
  98 The
  99 .Fa addr
 100 argument passed to
 101 .Fn gethostbyaddr
 102 should point to an address which is
 103 .Fa len
 104 bytes long,
 105 in binary form
 106 (i.e., not an IP address in human readable
 107 .Tn ASCII
 108 form).
 109 The
 110 .Fa af
 111 argument specifies the address family
 112 (e.g.\&
 113 .Dv AF_INET , AF_INET6 ,
 114 etc.) of this address.
 115 .Pp
 116 The structure returned contains either the information obtained from the name
 117 server,
 118 .Xr named 8 ,
 119 broken-out fields from a line in
 120 .Pa /etc/hosts ,
 121 or database entries supplied by the
 122 .Xr yp 8
 123 system.
 124 The order of the lookups is controlled by the
 125 .Sq hosts
 126 entry in
 127 .Xr nsswitch.conf 5 .
 128 .Bd -literal
 129 struct  hostent {
 130         char    *h_name;        /* official name of host */
 131         char    **h_aliases;    /* alias list */
 132         int     h_addrtype;     /* host address type */
 133         int     h_length;       /* length of address */
 134         char    **h_addr_list;  /* list of addresses from name server */
 135 };
 136 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 137 .Ed
 138 .Pp
 139 The members of this structure are:
 140 .Bl -tag -width h_addr_list
 141 .It Va h_name
 142 Official name of the host.
 143 .It Va h_aliases
 144 A
 145 .Dv NULL Ns -terminated
 146 array of alternate names for the host.
 147 .It Va h_addrtype
 148 The type of address being returned; usually
 149 .Dv AF_INET .
 150 .It Va h_length
 151 The length, in bytes, of the address.
 152 .It Va h_addr_list
 153 A
 154 .Dv NULL Ns -terminated
 155 array of network addresses for the host.
 156 Host addresses are returned in network byte order.
 157 .It Va h_addr
 158 The first address in
 159 .Va h_addr_list ;
 160 this is for backward compatibility.
 161 .El
 162 .Pp
 163 When using the nameserver,
 164 .Fn gethostbyname
 165 and
 166 .Fn gethostbyname2
 167 will search for the named host in the current domain and its parents
 168 unless the name ends in a dot.
 169 If the name contains no dot, and if the environment variable
 170 .Dq Ev HOSTALIASES
 171 contains the name of an alias file, the alias file will first be searched
 172 for an alias matching the input name.
 173 See
 174 .Xr hostname 7
 175 for the domain search procedure and the alias file format.
 176 .Pp
 177 The
 178 .Fn gethostbyname2
 179 function is an evolution of
 180 .Fn gethostbyname
 181 which is intended to allow lookups in address families other than
 182 .Dv AF_INET ,
 183 for example
 184 .Dv AF_INET6 .
 185 .Pp
 186 The
 187 .Fn sethostent
 188 function
 189 may be used to request the use of a connected
 190 .Tn TCP
 191 socket for queries.
 192 If the
 193 .Fa stayopen
 194 flag is non-zero,
 195 this sets the option to send all queries to the name server using
 196 .Tn TCP
 197 and to retain the connection after each call to
 198 .Fn gethostbyname ,
 199 .Fn gethostbyname2
 200 or
 201 .Fn gethostbyaddr .
 202 Otherwise, queries are performed using
 203 .Tn UDP
 204 datagrams.
 205 .Pp
 206 The
 207 .Fn endhostent
 208 function
 209 closes the
 210 .Tn TCP
 211 connection.
 212 .Pp
 213 The
 214 .Fn herror
 215 function writes a message to the diagnostic output consisting of the
 216 string argument
 217 .Fa string ,
 218 the constant string
 219 .Qq Li ":\ " ,
 220 and a message corresponding to the value of
 221 .Va h_errno .
 222 .Pp
 223 The
 224 .Fn hstrerror
 225 function returns a string which is the message text corresponding to the
 226 value of the
 227 .Fa err
 228 argument.
 229 .Sh FILES
 230 .Bl -tag -width /etc/nsswitch.conf -compact
 231 .It Pa /etc/hosts
 232 .It Pa /etc/nsswitch.conf
 233 .It Pa /etc/resolv.conf
 234 .El
 235 .Sh EXAMPLES
 236 Print out the hostname associated with a specific IP address:
 237 .Bd -literal -offset indent
 238 const char *ipstr = "127.0.0.1";
 239 struct in_addr ip;
 240 struct hostent *hp;
 241
 242 if (!inet_aton(ipstr, &ip))
 243         errx(1, "can't parse IP address %s", ipstr);
 244
 245 if ((hp = gethostbyaddr((const void *)&ip,
 246     sizeof ip, AF_INET)) == NULL)
 247         errx(1, "no name associated with %s", ipstr);
 248
 249 printf("name associated with %s is %s\en", ipstr, hp->h_name);
 250 .Ed
 251 .Sh DIAGNOSTICS
 252 Error return status from
 253 .Fn gethostbyname ,
 254 .Fn gethostbyname2
 255 and
 256 .Fn gethostbyaddr
 257 is indicated by return of a
 258 .Dv NULL
 259 pointer.
 260 The integer
 261 .Va h_errno
 262 may then be checked to see whether this is a temporary failure
 263 or an invalid or unknown host.
 264 The routine
 265 .Fn herror
 266 can be used to print an error message describing the failure.
 267 If its argument
 268 .Fa string
 269 is
 270 .Pf non- Dv NULL ,
 271 it is printed, followed by a colon and a space.
 272 The error message is printed with a trailing newline.
 273 .Pp
 274 The variable
 275 .Va h_errno
 276 can have the following values:
 277 .Bl -tag -width HOST_NOT_FOUND
 278 .It Dv HOST_NOT_FOUND
 279 No such host is known.
 280 .It Dv TRY_AGAIN
 281 This is usually a temporary error
 282 and means that the local server did not receive
 283 a response from an authoritative server.
 284 A retry at some later time may succeed.
 285 .It Dv NO_RECOVERY
 286 Some unexpected server failure was encountered.
 287 This is a non-recoverable error.
 288 .It Dv NO_DATA
 289 The requested name is valid but does not have an IP address;
 290 this is not a temporary error.
 291 This means that the name is known to the name server but there is no address
 292 associated with this name.
 293 Another type of request to the name server using this domain name
 294 will result in an answer;
 295 for example, a mail-forwarder may be registered for this domain.
 296 .El
 297 .Sh SEE ALSO
 298 .Xr getaddrinfo 3 ,
 299 .Xr getnameinfo 3 ,
 300 .Xr inet_aton 3 ,
 301 .Xr resolver 3 ,
 302 .Xr hosts 5 ,
 303 .Xr hostname 7 ,
 304 .Xr named 8
 305 .Sh CAVEAT
 306 The
 307 .Fn gethostent
 308 function
 309 is defined, and
 310 .Fn sethostent
 311 and
 312 .Fn endhostent
 313 are redefined,
 314 when
 315 .Lb libc
 316 is built to use only the routines to lookup in
 317 .Pa /etc/hosts
 318 and not the name server.
 319 .Pp
 320 The
 321 .Fn gethostent
 322 function
 323 reads the next line of
 324 .Pa /etc/hosts ,
 325 opening the file if necessary.
 326 .Pp
 327 The
 328 .Fn sethostent
 329 function
 330 opens and/or rewinds the file
 331 .Pa /etc/hosts .
 332 If the
 333 .Fa stayopen
 334 argument is non-zero,
 335 the file will not be closed after each call to
 336 .Fn gethostbyname ,
 337 .Fn gethostbyname2
 338 or
 339 .Fn gethostbyaddr .
 340 .Pp
 341 The
 342 .Fn endhostent
 343 function
 344 closes the file.
 345 .Sh HISTORY
 346 The
 347 .Fn herror
 348 function appeared in
 349 .Bx 4.3 .
 350 The
 351 .Fn endhostent ,
 352 .Fn gethostbyaddr ,
 353 .Fn gethostbyname ,
 354 .Fn gethostent ,
 355 and
 356 .Fn sethostent
 357 functions appeared in
 358 .Bx 4.2 .
 359 The
 360 .Fn gethostbyname2
 361 function first appeared in
 362 .Tn BIND
 363 version 4.9.4.
 364 .Sh BUGS
 365 These functions use a thread-specific data storage;
 366 if the data is needed for future use, it should be
 367 copied before any subsequent calls overwrite it.
 368 .Pp
 369 Though these functions are thread-safe,
 370 still it is recommended to use the
 371 .Xr getaddrinfo 3
 372 family of functions, instead.
 373 .Pp
 374 Only the Internet
 375 address format is currently understood.