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 .PP
  34 .BI "void sethostent(int " stayopen );
  35 .B void endhostent(void);
  36 .PP
  37 .B [[deprecated]] extern int h_errno;
  38 .PP
  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 .PP
  43 .BI "[[deprecated]] void herror(const char *" s );
  44 .BI "[[deprecated]] const char *hstrerror(int " err );
  45 .PP
  46 /* System V/POSIX extension */
  47 .B struct hostent *gethostent(void);
  48 .PP
  49 /* GNU extensions */
  50 .B [[deprecated]]
  51 .BI "struct hostent *gethostbyname2(const char *" name ", int " af );
  52 .PP
  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 .PP
  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 .PP
  79 .RS -4
  80 Feature Test Macro Requirements for glibc (see
  81 .BR feature_test_macros (7)):
  82 .RE
  83 .PP
  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 .PP
  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 .PP
 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 .PP
 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 .PP
 138 The
 139 .BR endhostent ()
 140 function ends the use of a TCP connection for name
 141 server queries.
 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 .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 .PP
 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 .PP
 205 The (obsolete)
 206 .BR hstrerror ()
 207 function takes an error number
 208 (typically \fIh_errno\fP) and returns the corresponding message string.
 209 .PP
 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 .PP
 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 .PP
 234 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
 235 .PP
 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 .PP
 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 .ad l
 320 .nh
 321 .TS
 322 allbox;
 323 lb lb lbx
 324 l l l.
 325 Interface       Attribute       Value
 326 T{
 327 .BR gethostbyname ()
 328 T}      Thread safety   T{
 329 MT-Unsafe race:hostbyname env
 330 locale
 331 T}
 332 T{
 333 .BR gethostbyaddr ()
 334 T}      Thread safety   T{
 335 MT-Unsafe race:hostbyaddr env
 336 locale
 337 T}
 338 T{
 339 .BR sethostent (),
 340 .BR endhostent (),
 341 .BR gethostent_r ()
 342 T}      Thread safety   T{
 343 MT-Unsafe race:hostent env
 344 locale
 345 T}
 346 T{
 347 .BR herror (),
 348 .BR hstrerror ()
 349 T}      Thread safety   MT-Safe
 350 T{
 351 .BR gethostent ()
 352 T}      Thread safety   T{
 353 MT-Unsafe race:hostent
 354 race:hostentbuf env locale
 355 T}
 356 T{
 357 .BR gethostbyname2 ()
 358 T}      Thread safety   T{
 359 MT-Unsafe race:hostbyname2
 360 env locale
 361 T}
 362 T{
 363 .BR gethostbyaddr_r (),
 364 .BR gethostbyname_r (),
 365 .BR gethostbyname2_r ()
 366 T}      Thread safety   MT-Safe env locale
 367 .TE
 368 .hy
 369 .ad
 370 .sp 1
 371 In the above table,
 372 .I hostent
 373 in
 374 .I race:hostent
 375 signifies that if any of the functions
 376 .BR sethostent (),
 377 .BR gethostent (),
 378 .BR gethostent_r (),
 379 or
 380 .BR endhostent ()
 381 are used in parallel in different threads of a program,
 382 then data races could occur.
 383 .SH STANDARDS
 384 POSIX.1-2001 specifies
 385 .BR gethostbyname (),
 386 .BR gethostbyaddr (),
 387 .BR sethostent (),
 388 .BR endhostent (),
 389 .BR gethostent (),
 390 and
 391 .IR h_errno ;
 392 .BR gethostbyname (),
 393 .BR gethostbyaddr (),
 394 and
 395 .I h_errno
 396 are marked obsolescent in that standard.
 397 POSIX.1-2008 removes the specifications of
 398 .BR gethostbyname (),
 399 .BR gethostbyaddr (),
 400 and
 401 .IR h_errno ,
 402 recommending the use of
 403 .BR getaddrinfo (3)
 404 and
 405 .BR getnameinfo (3)
 406 instead.
 407 .SH NOTES
 408 The functions
 409 .BR gethostbyname ()
 410 and
 411 .BR gethostbyaddr ()
 412 may return pointers to static data, which may be overwritten by
 413 later calls.
 414 Copying the
 415 .I struct hostent
 416 does not suffice, since it contains pointers; a deep copy is required.
 417 .PP
 418 In the original BSD implementation the
 419 .I len
 420 argument
 421 of
 422 .BR gethostbyname ()
 423 was an
 424 .IR int .
 425 The SUSv2 standard is buggy and declares the
 426 .I len
 427 argument of
 428 .BR gethostbyaddr ()
 429 to be of type
 430 .IR size_t .
 431 (That is wrong, because it has to be
 432 .IR int ,
 433 and
 434 .I size_t
 435 is not.
 436 POSIX.1-2001 makes it
 437 .IR socklen_t ,
 438 which is OK.)
 439 See also
 440 .BR accept (2).
 441 .PP
 442 The BSD prototype for
 443 .BR gethostbyaddr ()
 444 uses
 445 .I "const char\ *"
 446 for the first argument.
 447 .SS System V/POSIX extension
 448 POSIX requires the
 449 .BR gethostent ()
 450 call, which should return the next entry in the host data base.
 451 When using DNS/BIND this does not make much sense, but it may
 452 be reasonable if the host data base is a file that can be read
 453 line by line.
 454 On many systems, a routine of this name reads
 455 from the file
 456 .IR /etc/hosts .
 457 .\" e.g., Linux, FreeBSD, UnixWare, HP-UX
 458 It may be available only when the library was built without DNS support.
 459 .\" e.g., FreeBSD, AIX
 460 The glibc version will ignore ipv6 entries.
 461 This function is not reentrant,
 462 and glibc adds a reentrant version
 463 .BR gethostent_r ().
 464 .SS GNU extensions
 465 glibc2 also has a
 466 .BR gethostbyname2 ()
 467 that works like
 468 .BR gethostbyname (),
 469 but permits to specify the address family to which the address must belong.
 470 .PP
 471 glibc2 also has reentrant versions
 472 .BR gethostent_r (),
 473 .BR gethostbyaddr_r (),
 474 .BR gethostbyname_r (),
 475 and
 476 .BR gethostbyname2_r ().
 477 The caller supplies a
 478 .I hostent
 479 structure
 480 .I ret
 481 which will be filled in on success, and a temporary work buffer
 482 .I buf
 483 of size
 484 .IR buflen .
 485 After the call,
 486 .I result
 487 will point to the result on success.
 488 In case of an error
 489 or if no entry is found
 490 .I result
 491 will be NULL.
 492 The functions return 0 on success and a nonzero error number on failure.
 493 In addition to the errors returned by the nonreentrant
 494 versions of these functions, if
 495 .I buf
 496 is too small, the functions will return
 497 .BR ERANGE ,
 498 and the call should be retried with a larger buffer.
 499 The global variable
 500 .I h_errno
 501 is not modified, but the address of a variable in which to store error numbers
 502 is passed in
 503 .IR h_errnop .
 504 .SH BUGS
 505 .BR gethostbyname ()
 506 does not recognize components of a dotted IPv4 address string
 507 that are expressed in hexadecimal.
 508 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973
 509 .SH SEE ALSO
 510 .BR getaddrinfo (3),
 511 .\" .BR getipnodebyaddr (3),
 512 .\" .BR getipnodebyname (3),
 513 .BR getnameinfo (3),
 514 .BR inet (3),
 515 .BR inet_ntop (3),
 516 .BR inet_pton (3),
 517 .BR resolver (3),
 518 .BR hosts (5),
 519 .BR nsswitch.conf (5),
 520 .BR hostname (7),
 521 .BR named (8)
 522 .\" .BR resolv+ (8)