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 .\" 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: src/lib/libc/net/gethostbyname.3,v 1.38 2007/01/09 00:28:02 imp Exp $
  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 type"
  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 type
 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 information obtained from
 117 .Xr mDNSResponder 8 ,
 118 including records in
 119 .Pa /etc/hosts .
 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 8
 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 argument
 221 .Fa string ,
 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 argument.
 233 .Pp
 234 Historically, passing a host's own hostname to
 235 .Fn gethostbyname
 236 or
 237 .Fn gethostbyname2
 238 has been a popular
 239 technique for determining that host's IP address(es), but this is fragile,
 240 and doesn't work reliably in all cases. The appropriate way for software to
 241 discover the IP address(es) of the host it is running on is to use
 242 .Xr getifaddrs 3 .
 243 .Pp
 244 .Sh FILES
 245 .Bl -tag -width /etc/nsswitch.conf -compact
 246 .It Pa /etc/hosts
 247 .\".It Pa /etc/nsswitch.conf
 248 .It Pa /etc/resolv.conf
 249 .El
 250 .Sh EXAMPLES
 251 Print out the hostname associated with a specific IP address:
 252 .Bd -literal -offset indent
 253 const char *ipstr = "127.0.0.1";
 254 struct in_addr ip;
 255 struct hostent *hp;
 256
 257 if (!inet_aton(ipstr, &ip))
 258         errx(1, "can't parse IP address %s", ipstr);
 259
 260 if ((hp = gethostbyaddr((const void *)&ip,
 261     sizeof ip, AF_INET)) == NULL)
 262         errx(1, "no name associated with %s", ipstr);
 263
 264 printf("name associated with %s is %s\en", ipstr, hp->h_name);
 265 .Ed
 266 .Sh DIAGNOSTICS
 267 Error return status from
 268 .Fn gethostbyname ,
 269 .Fn gethostbyname2
 270 and
 271 .Fn gethostbyaddr
 272 is indicated by return of a
 273 .Dv NULL
 274 pointer.
 275 The integer
 276 .Va h_errno
 277 may then be checked to see whether this is a temporary failure
 278 or an invalid or unknown host.
 279 The routine
 280 .Fn herror
 281 can be used to print an error message describing the failure.
 282 If its argument
 283 .Fa string
 284 is
 285 .Pf non- Dv NULL ,
 286 it is printed, followed by a colon and a space.
 287 The error message is printed with a trailing newline.
 288 .Pp
 289 The variable
 290 .Va h_errno
 291 can have the following values:
 292 .Bl -tag -width HOST_NOT_FOUND
 293 .It Dv HOST_NOT_FOUND
 294 No such host is known.
 295 .It Dv TRY_AGAIN
 296 This is usually a temporary error
 297 and means that the local server did not receive
 298 a response from an authoritative server.
 299 A retry at some later time may succeed.
 300 .It Dv NO_RECOVERY
 301 Some unexpected server failure was encountered.
 302 This is a non-recoverable error.
 303 .It Dv NO_DATA
 304 The requested name is valid but does not have an IP address;
 305 this is not a temporary error.
 306 This means that the name is known to the name server but there is no address
 307 associated with this name.
 308 Another type of request to the name server using this domain name
 309 will result in an answer;
 310 for example, a mail-forwarder may be registered for this domain.
 311 .El
 312 .Sh SEE ALSO
 313 .Xr getaddrinfo 3 ,
 314 .Xr getnameinfo 3 ,
 315 .Xr inet_aton 3 ,
 316 .Xr resolver 3 ,
 317 .Xr hosts 5 ,
 318 .Xr hostname 7 ,
 319 .Xr mDNSResponder 8
 320 .\".Xr named 8
 321 .Sh CAVEAT
 322 The
 323 .Fn gethostent
 324 function
 325 is defined, and
 326 .Fn sethostent
 327 and
 328 .Fn endhostent
 329 are redefined,
 330 when
 331 .Lb libc
 332 is built to use only the routines to lookup in
 333 .Pa /etc/hosts
 334 and not the name server.
 335 .Pp
 336 The
 337 .Fn gethostent
 338 function
 339 reads the next line of
 340 .Pa /etc/hosts ,
 341 opening the file if necessary.
 342 .Pp
 343 The
 344 .Fn sethostent
 345 function
 346 opens and/or rewinds the file
 347 .Pa /etc/hosts .
 348 If the
 349 .Fa stayopen
 350 argument is non-zero,
 351 the file will not be closed after each call to
 352 .Fn gethostbyname ,
 353 .Fn gethostbyname2
 354 or
 355 .Fn gethostbyaddr .
 356 .Pp
 357 The
 358 .Fn endhostent
 359 function
 360 closes the file.
 361 .Sh HISTORY
 362 The
 363 .Fn herror
 364 function appeared in
 365 .Bx 4.3 .
 366 The
 367 .Fn endhostent ,
 368 .Fn gethostbyaddr ,
 369 .Fn gethostbyname ,
 370 .Fn gethostent ,
 371 and
 372 .Fn sethostent
 373 functions appeared in
 374 .Bx 4.2 .
 375 The
 376 .Fn gethostbyname2
 377 function first appeared in
 378 .Tn BIND
 379 version 4.9.4.
 380 .Sh BUGS
 381 These functions use a thread-specific data storage;
 382 if the data is needed for future use, it should be
 383 copied before any subsequent calls overwrite it.
 384 .Pp
 385 Though these functions are thread-safe,
 386 still it is recommended to use the
 387 .Xr getaddrinfo 3
 388 family of functions, instead.
 389 .Pp
 390 Only the Internet
 391 address format is currently understood.