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