man3/gethostbyname.3

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