original/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 2014-03-11 "" "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 or an IPv6 address in colon (and possibly dot) notation.
 155 (See RFC\ 1884 for the description of IPv6 addresses.)
 156 If
 157 .I name
 158 is an IPv4 or IPv6 address, no lookup is performed and
 159 .BR gethostbyname ()
 160 simply copies
 161 .I name
 162 into the
 163 .I h_name
 164 field and its
 165 .I struct in_addr
 166 equivalent into the
 167 .I h_addr_list[0]
 168 field of the returned
 169 .I hostent
 170 structure.
 171 If
 172 .I name
 173 doesn't end in a dot and the environment variable
 174 .B HOSTALIASES
 175 is set, the alias file pointed to by
 176 .B HOSTALIASES
 177 will first be searched for
 178 .I name
 179 (see
 180 .BR hostname (7)
 181 for the file format).
 182 The current domain and its parents are searched unless \fIname\fP
 183 ends in a dot.
 184 .PP
 185 The
 186 .BR gethostbyaddr ()
 187 function returns a structure of type \fIhostent\fP
 188 for the given host address \fIaddr\fP of length \fIlen\fP and address type
 189 \fItype\fP.
 190 Valid address types are
 191 .B AF_INET
 192 and
 193 .BR AF_INET6 .
 194 The host address argument is a pointer to a struct of a type depending
 195 on the address type, for example a \fIstruct in_addr *\fP (probably
 196 obtained via a call to
 197 .BR inet_addr (3))
 198 for address type
 199 .BR AF_INET .
 200 .PP
 201 The
 202 .BR sethostent ()
 203 function specifies, if \fIstayopen\fP is true (1),
 204 that a connected TCP socket should be used for the name server queries and
 205 that the connection should remain open during successive queries.
 206 Otherwise, name server queries will use UDP datagrams.
 207 .PP
 208 The
 209 .BR endhostent ()
 210 function ends the use of a TCP connection for name
 211 server queries.
 212 .PP
 213 The (obsolete)
 214 .BR herror ()
 215 function prints the error message associated
 216 with the current value of \fIh_errno\fP on \fIstderr\fP.
 217 .PP
 218 The (obsolete)
 219 .BR hstrerror ()
 220 function takes an error number
 221 (typically \fIh_errno\fP) and returns the corresponding message string.
 222 .PP
 223 The domain name queries carried out by
 224 .BR gethostbyname ()
 225 and
 226 .BR gethostbyaddr ()
 227 use a combination of any or all of the name server
 228 .BR named (8),
 229 a broken out line from \fI/etc/hosts\fP, and the Network
 230 Information Service (NIS or YP), depending upon the contents of the
 231 \fIorder\fP line in
 232 .IR /etc/host.conf .
 233 .\" (See
 234 .\" .BR resolv+ (8)).
 235 The default action is to query
 236 .BR named (8),
 237 followed by
 238 .IR /etc/hosts .
 239 .PP
 240 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
 241 .sp
 242 .in +4n
 243 .nf
 244 .ne 7
 245 struct hostent {
 246     char  *h_name;            /* official name of host */
 247     char **h_aliases;         /* alias list */
 248     int    h_addrtype;        /* host address type */
 249     int    h_length;          /* length of address */
 250     char **h_addr_list;       /* list of addresses */
 251 }
 252 #define h_addr h_addr_list[0] /* for backward compatibility */
 253 .fi
 254 .in
 255 .PP
 256 The members of the \fIhostent\fP structure are:
 257 .TP
 258 .I h_name
 259 The official name of the host.
 260 .TP
 261 .I h_aliases
 262 An array of alternative names for the host, terminated by a null pointer.
 263 .TP
 264 .I h_addrtype
 265 The type of address; always
 266 .B AF_INET
 267 or
 268 .B AF_INET6
 269 at present.
 270 .TP
 271 .I h_length
 272 The length of the address in bytes.
 273 .TP
 274 .I h_addr_list
 275 An array of pointers to network addresses for the host (in network byte
 276 order), terminated by a null pointer.
 277 .TP
 278 .I h_addr
 279 The first address in \fIh_addr_list\fP for backward compatibility.
 280 .SH RETURN VALUE
 281 The
 282 .BR gethostbyname ()
 283 and
 284 .BR gethostbyaddr ()
 285 functions return the
 286 .I hostent
 287 structure or a null pointer if an error occurs.
 288 On error, the
 289 .I h_errno
 290 variable holds an error number.
 291 When non-NULL, the return value may point at static data, see the notes below.
 292 .SH ERRORS
 293 The variable \fIh_errno\fP can have the following values:
 294 .TP
 295 .B HOST_NOT_FOUND
 296 The specified host is unknown.
 297 .TP
 298 .BR NO_ADDRESS " or " NO_DATA
 299 The requested name is valid but does not have an IP address.
 300 .TP
 301 .B NO_RECOVERY
 302 A nonrecoverable name server error occurred.
 303 .TP
 304 .B TRY_AGAIN
 305 A temporary error occurred on an authoritative name server.
 306 Try again later.
 307 .SH FILES
 308 .TP
 309 .I /etc/host.conf
 310 resolver configuration file
 311 .TP
 312 .I /etc/hosts
 313 host database file
 314 .TP
 315 .I /etc/nsswitch.conf
 316 name service switch configuration
 317 .SH CONFORMING TO
 318 POSIX.1-2001 specifies
 319 .BR gethostbyname (),
 320 .BR gethostbyaddr (),
 321 .BR sethostent (),
 322 .BR endhostent (),
 323 .BR gethostent (),
 324 and
 325 .IR h_errno ;
 326 .BR gethostbyname (),
 327 .BR gethostbyaddr (),
 328 and
 329 .IR h_errno
 330 are marked obsolescent in that standard.
 331 POSIX.1-2008 removes the specifications of
 332 .BR gethostbyname (),
 333 .BR gethostbyaddr (),
 334 and
 335 .IR h_errno ,
 336 recommending the use of
 337 .BR getaddrinfo (3)
 338 and
 339 .BR getnameinfo (3)
 340 instead.
 341 .SH NOTES
 342 The functions
 343 .BR gethostbyname ()
 344 and
 345 .BR gethostbyaddr ()
 346 may return pointers to static data, which may be overwritten by
 347 later calls.
 348 Copying the
 349 .I struct hostent
 350 does not suffice, since it contains pointers; a deep copy is required.
 351 .LP
 352 In the original BSD implementation the
 353 .I len
 354 argument
 355 of
 356 .BR gethostbyname ()
 357 was an
 358 .IR int .
 359 The SUSv2 standard is buggy and declares the
 360 .I len
 361 argument of
 362 .BR gethostbyaddr ()
 363 to be of type
 364 .IR size_t .
 365 (That is wrong, because it has to be
 366 .IR int ,
 367 and
 368 .I size_t
 369 is not.
 370 POSIX.1-2001 makes it
 371 .IR socklen_t ,
 372 which is OK.)
 373 See also
 374 .BR accept (2).
 375 .LP
 376 The BSD prototype for
 377 .BR gethostbyaddr ()
 378 uses
 379 .I "const char\ *"
 380 for the first argument.
 381 .SS System V/POSIX extension
 382 POSIX requires the
 383 .BR gethostent ()
 384 call, that should return the next entry in the host data base.
 385 When using DNS/BIND this does not make much sense, but it may
 386 be reasonable if the host data base is a file that can be read
 387 line by line.
 388 On many systems a routine of this name reads
 389 from the file
 390 .IR /etc/hosts .
 391 .\" e.g., Linux, FreeBSD, UnixWare, HP-UX
 392 It may be available only when the library was built without DNS support.
 393 .\" e.g., FreeBSD, AIX
 394 The glibc version will ignore ipv6 entries.
 395 This function is not reentrant,
 396 and glibc adds a reentrant version
 397 .BR gethostent_r ().
 398 .SS GNU extensions
 399 Glibc2 also has a
 400 .BR gethostbyname2 ()
 401 that works like
 402 .BR gethostbyname (),
 403 but permits to specify the address family to which the address must belong.
 404 .LP
 405 Glibc2 also has reentrant versions
 406 .BR gethostent_r (),
 407 .BR gethostbyaddr_r (),
 408 .BR gethostbyname_r ()
 409 and
 410 .BR gethostbyname2_r ().
 411 The caller supplies a
 412 .I hostent
 413 structure
 414 .I ret
 415 which will be filled in on success, and a temporary work buffer
 416 .I buf
 417 of size
 418 .IR buflen .
 419 After the call,
 420 .I result
 421 will point to the result on success.
 422 In case of an error
 423 or if no entry is found
 424 .I result
 425 will be NULL.
 426 The functions return 0 on success and a nonzero error number on failure.
 427 In addition to the errors returned by the nonreentrant
 428 versions of these functions, if
 429 .I buf
 430 is too small, the functions will return
 431 .BR ERANGE ,
 432 and the call should be retried with a larger buffer.
 433 The global variable
 434 .I h_errno
 435 is not modified, but the address of a variable in which to store error numbers
 436 is passed in
 437 .IR h_errnop .
 438 .SH BUGS
 439 .BR gethostbyname ()
 440 does not recognize components of a dotted IPv4 address string
 441 that are expressed in hexadecimal.
 442 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973
 443 .SH SEE ALSO
 444 .BR getaddrinfo (3),
 445 .\" .BR getipnodebyaddr (3),
 446 .\" .BR getipnodebyname (3),
 447 .BR getnameinfo (3),
 448 .BR inet (3),
 449 .BR inet_ntop (3),
 450 .BR inet_pton (3),
 451 .BR resolver (3),
 452 .BR hosts (5),
 453 .BR nsswitch.conf (5),
 454 .BR hostname (7),
 455 .BR named (8)
 456 .\" .BR resolv+ (8)
 457 .SH COLOPHON
 458 This page is part of release 3.79 of the Linux
 459 .I man-pages
 460 project.
 461 A description of the project,
 462 information about reporting bugs,
 463 and the latest version of this page,
 464 can be found at
 465 \%http://www.kernel.org/doc/man\-pages/.