man3/gethostbyname.3

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