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