man3/gethostbyname.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified 1993-05-22, David Metcalfe
  10 .\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu)
  11 .\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl)
  12 .\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl)
  13 .\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl)
  14 .\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl)
  15 .\" Modified 2002-08-05, Michael Kerrisk
  16 .\" Modified 2004-10-31, Andries Brouwer
  17 .\"
  18 .TH gethostbyname 3 (date) "Linux man-pages (unreleased)"
  19 .SH NAME
  20 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
  21 h_errno,
  22 herror, hstrerror,
  23 gethostbyaddr_r,
  24 gethostbyname2, gethostbyname2_r, gethostbyname_r,
  25 gethostent_r \- get network host entry
  26 .SH LIBRARY
  27 Standard C library
  28 .RI ( libc ", " \-lc )
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <netdb.h>
  32 .PP
  33 .BI "void sethostent(int " stayopen );
  34 .B void endhostent(void);
  35 .PP
  36 .B [[deprecated]] extern int h_errno;
  37 .PP
  38 .BI "[[deprecated]] struct hostent *gethostbyname(const char *" name );
  39 .BI "[[deprecated]] struct hostent *gethostbyaddr(const void *" addr ,
  40 .BI "                                      socklen_t " len ", int " type );
  41 .PP
  42 .BI "[[deprecated]] void herror(const char *" s );
  43 .BI "[[deprecated]] const char *hstrerror(int " err );
  44 .PP
  45 /* System V/POSIX extension */
  46 .B struct hostent *gethostent(void);
  47 .PP
  48 /* GNU extensions */
  49 .B [[deprecated]]
  50 .BI "struct hostent *gethostbyname2(const char *" name ", int " af );
  51 .PP
  52 .BI "int gethostent_r(struct hostent *restrict " ret ,
  53 .BI "                 char *restrict " buf ", size_t " buflen ,
  54 .BI "                 struct hostent **restrict " result ,
  55 .BI "                 int *restrict " h_errnop );
  56 .PP
  57 .B [[deprecated]]
  58 .BI "int gethostbyaddr_r(const void *restrict " addr ", socklen_t " len \
  59 ", int " type ,
  60 .BI "                 struct hostent *restrict " ret ,
  61 .BI "                 char *restrict " buf ", size_t " buflen ,
  62 .BI "                 struct hostent **restrict " result ,
  63 .BI "                 int *restrict " h_errnop );
  64 .B [[deprecated]]
  65 .BI "int gethostbyname_r(const char *restrict " name ,
  66 .BI "                 struct hostent *restrict " ret ,
  67 .BI "                 char *restrict " buf ", size_t " buflen ,
  68 .BI "                 struct hostent **restrict " result ,
  69 .BI "                 int *restrict " h_errnop );
  70 .B [[deprecated]]
  71 .BI "int gethostbyname2_r(const char *restrict " name ", int " af,
  72 .BI "                 struct hostent *restrict " ret ,
  73 .BI "                 char *restrict " buf ", size_t " buflen ,
  74 .BI "                 struct hostent **restrict " result ,
  75 .BI "                 int *restrict " h_errnop );
  76 .fi
  77 .PP
  78 .RS -4
  79 Feature Test Macro Requirements for glibc (see
  80 .BR feature_test_macros (7)):
  81 .RE
  82 .PP
  83 .BR gethostbyname2 (),
  84 .BR gethostent_r (),
  85 .BR gethostbyaddr_r (),
  86 .BR gethostbyname_r (),
  87 .BR gethostbyname2_r ():
  88 .nf
  89     Since glibc 2.19:
  90         _DEFAULT_SOURCE
  91     Glibc up to and including 2.19:
  92         _BSD_SOURCE || _SVID_SOURCE
  93 .fi
  94 .PP
  95 .BR herror (),
  96 .BR hstrerror ():
  97 .nf
  98     Since glibc 2.19:
  99         _DEFAULT_SOURCE
 100     Glibc 2.8 to 2.19:
 101         _BSD_SOURCE || _SVID_SOURCE
 102     Before glibc 2.8:
 103         none
 104 .fi
 105 .PP
 106 .BR h_errno :
 107 .nf
 108     Since glibc 2.19
 109         _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
 110     Glibc 2.12 to 2.19:
 111         _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
 112     Before glibc 2.12:
 113         none
 114 .fi
 115 .SH DESCRIPTION
 116 The
 117 .BR gethostbyname* (),
 118 .BR gethostbyaddr* (),
 119 .BR herror (),
 120 and
 121 .BR hstrerror ()
 122 functions are obsolete.
 123 Applications should use
 124 .BR getaddrinfo (3),
 125 .BR getnameinfo (3),
 126 and
 127 .BR gai_strerror (3)
 128 instead.
 129 .PP
 130 The
 131 .BR sethostent ()
 132 function specifies, if \fIstayopen\fP is true (1),
 133 that a connected TCP socket should be used for the name server queries and
 134 that the connection should remain open during successive queries.
 135 Otherwise, name server queries will use UDP datagrams.
 136 .PP
 137 The
 138 .BR endhostent ()
 139 function ends the use of a TCP connection for name
 140 server queries.
 141 .PP
 142 The
 143 .BR gethostbyname ()
 144 function returns a structure of type
 145 .I hostent
 146 for the given host
 147 .IR name .
 148 Here
 149 .I name
 150 is either a hostname or an IPv4 address in standard dot notation (as for
 151 .BR inet_addr (3)).
 152 If
 153 .I name
 154 is an IPv4 address, no lookup is performed and
 155 .BR gethostbyname ()
 156 simply copies
 157 .I name
 158 into the
 159 .I h_name
 160 field and its
 161 .I struct in_addr
 162 equivalent into the
 163 .I h_addr_list[0]
 164 field of the returned
 165 .I hostent
 166 structure.
 167 If
 168 .I name
 169 doesn't end in a dot and the environment variable
 170 .B HOSTALIASES
 171 is set, the alias file pointed to by
 172 .B HOSTALIASES
 173 will first be searched for
 174 .I name
 175 (see
 176 .BR hostname (7)
 177 for the file format).
 178 The current domain and its parents are searched unless \fIname\fP
 179 ends in a dot.
 180 .PP
 181 The
 182 .BR gethostbyaddr ()
 183 function returns a structure of type \fIhostent\fP
 184 for the given host address \fIaddr\fP of length \fIlen\fP and address type
 185 \fItype\fP.
 186 Valid address types are
 187 .B AF_INET
 188 and
 189 .B AF_INET6
 190 (defined in
 191 .IR <sys/socket.h> ).
 192 The host address argument is a pointer to a struct of a type depending
 193 on the address type, for example a \fIstruct in_addr *\fP (probably
 194 obtained via a call to
 195 .BR inet_addr (3))
 196 for address type
 197 .BR AF_INET .
 198 .PP
 199 The (obsolete)
 200 .BR herror ()
 201 function prints the error message associated
 202 with the current value of \fIh_errno\fP on \fIstderr\fP.
 203 .PP
 204 The (obsolete)
 205 .BR hstrerror ()
 206 function takes an error number
 207 (typically \fIh_errno\fP) and returns the corresponding message string.
 208 .PP
 209 The domain name queries carried out by
 210 .BR gethostbyname ()
 211 and
 212 .BR gethostbyaddr ()
 213 rely on the Name Service Switch
 214 .RB ( nsswitch.conf (5))
 215 configured sources or a local name server
 216 .RB ( named (8)).
 217 The default action is to query the Name Service Switch
 218 .RB ( nsswitch.conf (5))
 219 configured sources, failing that, a local name server
 220 .RB ( named (8)).
 221 .\"
 222 .SS Historical
 223 The
 224 .BR nsswitch.conf (5)
 225 file is the modern way of controlling the order of host lookups.
 226 .PP
 227 In glibc 2.4 and earlier, the
 228 .I order
 229 keyword was used to control the order of host lookups as defined in
 230 .I /etc/host.conf
 231 .RB ( host.conf (5)).
 232 .PP
 233 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
 234 .PP
 235 .in +4n
 236 .EX
 237 struct hostent {
 238     char  *h_name;            /* official name of host */
 239     char **h_aliases;         /* alias list */
 240     int    h_addrtype;        /* host address type */
 241     int    h_length;          /* length of address */
 242     char **h_addr_list;       /* list of addresses */
 243 }
 244 #define h_addr h_addr_list[0] /* for backward compatibility */
 245 .EE
 246 .in
 247 .PP
 248 The members of the \fIhostent\fP structure are:
 249 .TP
 250 .I h_name
 251 The official name of the host.
 252 .TP
 253 .I h_aliases
 254 An array of alternative names for the host, terminated by a null pointer.
 255 .TP
 256 .I h_addrtype
 257 The type of address; always
 258 .B AF_INET
 259 or
 260 .B AF_INET6
 261 at present.
 262 .TP
 263 .I h_length
 264 The length of the address in bytes.
 265 .TP
 266 .I h_addr_list
 267 An array of pointers to network addresses for the host (in network byte
 268 order), terminated by a null pointer.
 269 .TP
 270 .I h_addr
 271 The first address in \fIh_addr_list\fP for backward compatibility.
 272 .SH RETURN VALUE
 273 The
 274 .BR gethostbyname ()
 275 and
 276 .BR gethostbyaddr ()
 277 functions return the
 278 .I hostent
 279 structure or a null pointer if an error occurs.
 280 On error, the
 281 .I h_errno
 282 variable holds an error number.
 283 When non-NULL, the return value may point at static data, see the notes below.
 284 .SH ERRORS
 285 The variable \fIh_errno\fP can have the following values:
 286 .TP
 287 .B HOST_NOT_FOUND
 288 The specified host is unknown.
 289 .TP
 290 .B NO_DATA
 291 The requested name is valid but does not have an IP address.
 292 Another type of request to the name server for this domain
 293 may return an answer.
 294 The constant
 295 .B NO_ADDRESS
 296 is a synonym for
 297 .BR NO_DATA .
 298 .TP
 299 .B NO_RECOVERY
 300 A nonrecoverable name server error occurred.
 301 .TP
 302 .B TRY_AGAIN
 303 A temporary error occurred on an authoritative name server.
 304 Try again later.
 305 .SH FILES
 306 .TP
 307 .I /etc/host.conf
 308 resolver configuration file
 309 .TP
 310 .I /etc/hosts
 311 host database file
 312 .TP
 313 .I /etc/nsswitch.conf
 314 name service switch configuration
 315 .SH ATTRIBUTES
 316 For an explanation of the terms used in this section, see
 317 .BR attributes (7).
 318 .ad l
 319 .nh
 320 .TS
 321 allbox;
 322 lb lb lbx
 323 l l l.
 324 Interface       Attribute       Value
 325 T{
 326 .BR gethostbyname ()
 327 T}      Thread safety   T{
 328 MT-Unsafe race:hostbyname env
 329 locale
 330 T}
 331 T{
 332 .BR gethostbyaddr ()
 333 T}      Thread safety   T{
 334 MT-Unsafe race:hostbyaddr env
 335 locale
 336 T}
 337 T{
 338 .BR sethostent (),
 339 .BR endhostent (),
 340 .BR gethostent_r ()
 341 T}      Thread safety   T{
 342 MT-Unsafe race:hostent env
 343 locale
 344 T}
 345 T{
 346 .BR herror (),
 347 .BR hstrerror ()
 348 T}      Thread safety   MT-Safe
 349 T{
 350 .BR gethostent ()
 351 T}      Thread safety   T{
 352 MT-Unsafe race:hostent
 353 race:hostentbuf env locale
 354 T}
 355 T{
 356 .BR gethostbyname2 ()
 357 T}      Thread safety   T{
 358 MT-Unsafe race:hostbyname2
 359 env locale
 360 T}
 361 T{
 362 .BR gethostbyaddr_r (),
 363 .BR gethostbyname_r (),
 364 .BR gethostbyname2_r ()
 365 T}      Thread safety   MT-Safe env locale
 366 .TE
 367 .hy
 368 .ad
 369 .sp 1
 370 In the above table,
 371 .I hostent
 372 in
 373 .I race:hostent
 374 signifies that if any of the functions
 375 .BR sethostent (),
 376 .BR gethostent (),
 377 .BR gethostent_r (),
 378 or
 379 .BR endhostent ()
 380 are used in parallel in different threads of a program,
 381 then data races could occur.
 382 .SH STANDARDS
 383 POSIX.1-2001 specifies
 384 .BR gethostbyname (),
 385 .BR gethostbyaddr (),
 386 .BR sethostent (),
 387 .BR endhostent (),
 388 .BR gethostent (),
 389 and
 390 .IR h_errno ;
 391 .BR gethostbyname (),
 392 .BR gethostbyaddr (),
 393 and
 394 .I h_errno
 395 are marked obsolescent in that standard.
 396 POSIX.1-2008 removes the specifications of
 397 .BR gethostbyname (),
 398 .BR gethostbyaddr (),
 399 and
 400 .IR h_errno ,
 401 recommending the use of
 402 .BR getaddrinfo (3)
 403 and
 404 .BR getnameinfo (3)
 405 instead.
 406 .SH NOTES
 407 The functions
 408 .BR gethostbyname ()
 409 and
 410 .BR gethostbyaddr ()
 411 may return pointers to static data, which may be overwritten by
 412 later calls.
 413 Copying the
 414 .I struct hostent
 415 does not suffice, since it contains pointers; a deep copy is required.
 416 .PP
 417 In the original BSD implementation the
 418 .I len
 419 argument
 420 of
 421 .BR gethostbyname ()
 422 was an
 423 .IR int .
 424 The SUSv2 standard is buggy and declares the
 425 .I len
 426 argument of
 427 .BR gethostbyaddr ()
 428 to be of type
 429 .IR size_t .
 430 (That is wrong, because it has to be
 431 .IR int ,
 432 and
 433 .I size_t
 434 is not.
 435 POSIX.1-2001 makes it
 436 .IR socklen_t ,
 437 which is OK.)
 438 See also
 439 .BR accept (2).
 440 .PP
 441 The BSD prototype for
 442 .BR gethostbyaddr ()
 443 uses
 444 .I "const char\ *"
 445 for the first argument.
 446 .SS System V/POSIX extension
 447 POSIX requires the
 448 .BR gethostent ()
 449 call, which should return the next entry in the host data base.
 450 When using DNS/BIND this does not make much sense, but it may
 451 be reasonable if the host data base is a file that can be read
 452 line by line.
 453 On many systems, a routine of this name reads
 454 from the file
 455 .IR /etc/hosts .
 456 .\" e.g., Linux, FreeBSD, UnixWare, HP-UX
 457 It may be available only when the library was built without DNS support.
 458 .\" e.g., FreeBSD, AIX
 459 The glibc version will ignore ipv6 entries.
 460 This function is not reentrant,
 461 and glibc adds a reentrant version
 462 .BR gethostent_r ().
 463 .SS GNU extensions
 464 Glibc2 also has a
 465 .BR gethostbyname2 ()
 466 that works like
 467 .BR gethostbyname (),
 468 but permits to specify the address family to which the address must belong.
 469 .PP
 470 Glibc2 also has reentrant versions
 471 .BR gethostent_r (),
 472 .BR gethostbyaddr_r (),
 473 .BR gethostbyname_r (),
 474 and
 475 .BR gethostbyname2_r ().
 476 The caller supplies a
 477 .I hostent
 478 structure
 479 .I ret
 480 which will be filled in on success, and a temporary work buffer
 481 .I buf
 482 of size
 483 .IR buflen .
 484 After the call,
 485 .I result
 486 will point to the result on success.
 487 In case of an error
 488 or if no entry is found
 489 .I result
 490 will be NULL.
 491 The functions return 0 on success and a nonzero error number on failure.
 492 In addition to the errors returned by the nonreentrant
 493 versions of these functions, if
 494 .I buf
 495 is too small, the functions will return
 496 .BR ERANGE ,
 497 and the call should be retried with a larger buffer.
 498 The global variable
 499 .I h_errno
 500 is not modified, but the address of a variable in which to store error numbers
 501 is passed in
 502 .IR h_errnop .
 503 .SH BUGS
 504 .BR gethostbyname ()
 505 does not recognize components of a dotted IPv4 address string
 506 that are expressed in hexadecimal.
 507 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973
 508 .SH SEE ALSO
 509 .BR getaddrinfo (3),
 510 .\" .BR getipnodebyaddr (3),
 511 .\" .BR getipnodebyname (3),
 512 .BR getnameinfo (3),
 513 .BR inet (3),
 514 .BR inet_ntop (3),
 515 .BR inet_pton (3),
 516 .BR resolver (3),
 517 .BR hosts (5),
 518 .BR nsswitch.conf (5),
 519 .BR hostname (7),
 520 .BR named (8)
 521 .\" .BR resolv+ (8)