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