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