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