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