man3/gethostbyname.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" References consulted:
  24 .\"     Linux libc source code
  25 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  26 .\"     386BSD man pages
  27 .\" Modified 1993-05-22, David Metcalfe
  28 .\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu)
  29 .\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl)
  30 .\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl)
  31 .\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl)
  32 .\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl)
  33 .\" Modified 2002-08-05, Michael Kerrisk
  34 .\" Modified 2004-10-31, Andries Brouwer
  35 .\"
  36 .TH GETHOSTBYNAME 3 2007-10-16 "" "Linux Programmer's Manual"
  37 .SH NAME
  38 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
  39 h_errno,
  40 herror, hstrerror,
  41 gethostbyaddr_r,
  42 gethostbyname2, gethostbyname2_r, gethostbyname_r,
  43 gethostent_r \- get network host entry
  44 .SH SYNOPSIS
  45 .nf
  46 .B #include <netdb.h>
  47 .B extern int h_errno;
  48 .sp
  49 .BI "struct hostent *gethostbyname(const char *" name );
  50 .sp
  51 .BR "#include <sys/socket.h>" "       /* for AF_INET */"
  52 .BI "struct hostent *gethostbyaddr(const void *" addr ,
  53 .BI "                              socklen_t " len ", int " type );
  54 .sp
  55 .BI "void sethostent(int " stayopen );
  56 .sp
  57 .B void endhostent(void);
  58 .sp
  59 .BI "void herror(const char *" s );
  60 .sp
  61 .BI "const char *hstrerror(int " err );
  62 .sp
  63 /* System V/POSIX extension */
  64 .br
  65 .B struct hostent *gethostent(void);
  66 .sp
  67 /* GNU extensions */
  68 .br
  69 .BI "struct hostent *gethostbyname2(const char *" name ", int " af );
  70 .sp
  71 .B "int gethostent_r("
  72 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
  73 .BI "        struct hostent **" result ", int *" h_errnop );
  74 .sp
  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 .sp
  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 .sp
  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 .sp
  88 .in -4n
  89 Feature Test Macro Requirements for glibc (see
  90 .BR feature_test_macros (7)):
  91 .in
  92 .sp
  93 .ad l
  94 .BR gethostbyname2 (),
  95 .BR gethostent_r (),
  96 .BR gethostbyaddr_r (),
  97 .BR gethostbyname_r (),
  98 .BR gethostbyname2_r ():
  99 _BSD_SOURCE || _SVID_SOURCE
 100 .ad b
 101 .SH DESCRIPTION
 102 These functions are obsolete.
 103 Applications should use
 104 .BR getaddrinfo (3)
 105 and
 106 .BR getnameinfo (3)
 107 instead.
 108
 109 The
 110 .BR gethostbyname ()
 111 function returns a structure of type
 112 .I hostent
 113 for the given host
 114 .IR name .
 115 Here
 116 .I name
 117 is either a host name, or an IPv4 address in standard dot notation,
 118 or an IPv6 address in colon (and possibly dot) notation.
 119 (See RFC\ 1884 for the description of IPv6 addresses.)
 120 If
 121 .I name
 122 is an IPv4 or IPv6 address, no lookup is performed and
 123 .BR gethostbyname ()
 124 simply copies
 125 .I name
 126 into the
 127 .I h_name
 128 field and its
 129 .I struct in_addr
 130 equivalent into the
 131 .I h_addr_list[0]
 132 field of the returned
 133 .I hostent
 134 structure.
 135 If
 136 .I name
 137 doesn't end in a dot and the environment variable
 138 .B HOSTALIASES
 139 is set, the alias file pointed to by
 140 .B HOSTALIASES
 141 will first be searched for
 142 .I name
 143 (see
 144 .BR hostname (7)
 145 for the file format).
 146 The current domain and its parents are searched unless \fIname\fP
 147 ends in a dot.
 148 .PP
 149 The
 150 .BR gethostbyaddr ()
 151 function returns a structure of type \fIhostent\fP
 152 for the given host address \fIaddr\fP of length \fIlen\fP and address type
 153 \fItype\fP.
 154 Valid address types are
 155 .B AF_INET
 156 and
 157 .BR AF_INET6 .
 158 The host address argument is a pointer to a struct of a type depending
 159 on the address type, for example a \fIstruct in_addr *\fP (probably
 160 obtained via a call to
 161 .BR inet_addr (3))
 162 for address type
 163 .BR AF_INET .
 164 .PP
 165 The
 166 .BR sethostent ()
 167 function specifies, if \fIstayopen\fP is true (1),
 168 that a connected TCP socket should be used for the name server queries and
 169 that the connection should remain open during successive queries.
 170 Otherwise, name server queries will use UDP datagrams.
 171 .PP
 172 The
 173 .BR endhostent ()
 174 function ends the use of a TCP connection for name
 175 server queries.
 176 .PP
 177 The (obsolete)
 178 .BR herror ()
 179 function prints the error message associated
 180 with the current value of \fIh_errno\fP on \fIstderr\fP.
 181 .PP
 182 The (obsolete)
 183 .BR hstrerror ()
 184 function takes an error number
 185 (typically \fIh_errno\fP) and returns the corresponding message string.
 186 .PP
 187 The domain name queries carried out by
 188 .BR gethostbyname ()
 189 and
 190 .BR gethostbyaddr ()
 191 use a combination of any or all of the name server
 192 .BR named (8),
 193 a broken out line from \fI/etc/hosts\fP, and the Network
 194 Information Service (NIS or YP), depending upon the contents of the
 195 \fIorder\fP line in
 196 .IR /etc/host.conf .
 197 .\" (See
 198 .\" .BR resolv+ (8)).
 199 The default action is to query
 200 .BR named (8),
 201 followed by
 202 .IR /etc/hosts .
 203 .PP
 204 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
 205 .sp
 206 .in +4n
 207 .nf
 208 .ne 7
 209 struct hostent {
 210     char  *h_name;            /* official name of host */
 211     char **h_aliases;         /* alias list */
 212     int    h_addrtype;        /* host address type */
 213     int    h_length;          /* length of address */
 214     char **h_addr_list;       /* list of addresses */
 215 }
 216 #define h_addr h_addr_list[0] /* for backward compatibility */
 217 .fi
 218 .in
 219 .PP
 220 The members of the \fIhostent\fP structure are:
 221 .TP
 222 .I h_name
 223 The official name of the host.
 224 .TP
 225 .I h_aliases
 226 An array of alternative names for the host, terminated by a NULL pointer.
 227 .TP
 228 .I h_addrtype
 229 The type of address; always
 230 .B AF_INET
 231 or
 232 .B AF_INET6
 233 at present.
 234 .TP
 235 .I h_length
 236 The length of the address in bytes.
 237 .TP
 238 .I h_addr_list
 239 An array of pointers to network addresses for the host (in network byte
 240 order), terminated by a NULL pointer.
 241 .TP
 242 .I h_addr
 243 The first address in \fIh_addr_list\fP for backward compatibility.
 244 .SH "RETURN VALUE"
 245 The
 246 .BR gethostbyname ()
 247 and
 248 .BR gethostbyaddr ()
 249 functions return the
 250 .I hostent
 251 structure or a NULL pointer if an error occurs.
 252 On error, the
 253 .I h_errno
 254 variable holds an error number.
 255 When non-NULL, the return value may point at static data, see the notes below.
 256 .SH ERRORS
 257 The variable \fIh_errno\fP can have the following values:
 258 .TP
 259 .B HOST_NOT_FOUND
 260 The specified host is unknown.
 261 .TP
 262 .BR NO_ADDRESS " or " NO_DATA
 263 The requested name is valid but does not have an IP address.
 264 .TP
 265 .B NO_RECOVERY
 266 A non-recoverable name server error occurred.
 267 .TP
 268 .B TRY_AGAIN
 269 A temporary error occurred on an authoritative name server.
 270 Try again later.
 271 .SH FILES
 272 .TP
 273 .I /etc/host.conf
 274 resolver configuration file
 275 .TP
 276 .I /etc/hosts
 277 host database file
 278 .TP
 279 .I /etc/nsswitch.conf
 280 name service switch configuration
 281 .SH "CONFORMING TO"
 282 POSIX.1-2001 specifies
 283 .BR gethostbyname (),
 284 .BR gethostbyaddr (),
 285 .BR sethostent (),
 286 .BR endhostent (),
 287 .BR gethostent (),
 288 and
 289 .IR h_errno .
 290 .\" FIXME . SUSv4 removes the specs for gethostbyname(),
 291 .\" gethostbyaddr(), and h_errno.
 292 .SH NOTES
 293 The functions
 294 .BR gethostbyname ()
 295 and
 296 .BR gethostbyaddr ()
 297 may return pointers to static data, which may be overwritten by
 298 later calls.
 299 Copying the
 300 .I struct hostent
 301 does not suffice, since it contains pointers; a deep copy is required.
 302 .LP
 303 In the original BSD implementation the
 304 .I len
 305 argument
 306 of
 307 .BR gethostbyname ()
 308 was an
 309 .IR int .
 310 The SUSv2 standard is buggy and declares the
 311 .I len
 312 parameter of
 313 .BR gethostbyaddr ()
 314 to be of type
 315 .IR size_t .
 316 (That is wrong, because it has to be
 317 .IR int ,
 318 and
 319 .I size_t
 320 is not.
 321 POSIX.1-2001 makes it
 322 .IR socklen_t ,
 323 which is OK.)
 324 See also
 325 .BR accept (2).
 326 .LP
 327 The BSD prototype for
 328 .BR gethostbyaddr ()
 329 uses
 330 .I const char *
 331 for the first argument.
 332 .LP
 333 POSIX.1-2001 marks
 334 .BR gethostbyaddr ()
 335 and
 336 .BR gethostbyname ()
 337 obsolescent.
 338 .\" FIXME . SUSv4 removes the specs for gethostbyname(),
 339 .\" gethostbyaddr(), and h_errno.
 340 See
 341 .BR getaddrinfo (3),
 342 .BR getnameinfo (3),
 343 .BR gai_strerror (3).
 344 .SS "System V/POSIX Extension"
 345 POSIX requires the
 346 .BR gethostent ()
 347 call, that should return the next entry in the host data base.
 348 When using DNS/BIND this does not make much sense, but it may
 349 be reasonable if the host data base is a file that can be read
 350 line by line.
 351 On many systems a routine of this name reads
 352 from the file
 353 .IR /etc/hosts .
 354 .\" e.g., Linux, FreeBSD, Unixware, HP-UX
 355 It may be available only when the library was built without DNS support.
 356 .\" e.g., FreeBSD, AIX
 357 The glibc version will ignore ipv6 entries.
 358 This function is not reentrant,
 359 and glibc adds a reentrant version
 360 .BR gethostent_r ().
 361 .SS "GNU Extensions"
 362 Glibc2 also has a
 363 .BR gethostbyname2 ()
 364 that works like
 365 .BR gethostbyname (),
 366 but permits to specify the address family to which the address must belong.
 367 .LP
 368 Glibc2 also has reentrant versions
 369 .BR gethostent_r (),
 370 .BR gethostbyaddr_r (),
 371 .BR gethostbyname_r ()
 372 and
 373 .BR gethostbyname2_r ().
 374 The caller supplies a
 375 .I hostent
 376 structure
 377 .I ret
 378 which will be filled in on success, and a temporary work buffer
 379 .I buf
 380 of size
 381 .IR buflen .
 382 After the call,
 383 .I result
 384 will point to the result on success.  In case of an error
 385 or if no entry is found
 386 .I result
 387 will be NULL.
 388 The functions return 0 on success and a non-zero error number on failure.
 389 In addition to the errors returned by the non-reentrant
 390 versions of these functions, if
 391 .I buf
 392 is too small, the functions will return
 393 .BR ERANGE ,
 394 and the call should be retried with a larger buffer.
 395 The global variable
 396 .I h_errno
 397 is not modified, but the address of a variable in which to store error numbers
 398 is passed in
 399 .IR h_errnop .
 400 .SH "SEE ALSO"
 401 .BR getaddrinfo (3),
 402 .\" .BR getipnodebyaddr (3),
 403 .\" .BR getipnodebyname (3),
 404 .BR getnameinfo (3),
 405 .BR inet_ntop (3),
 406 .BR inet_pton (3),
 407 .BR resolver (3),
 408 .BR hosts (5),
 409 .BR nsswitch.conf (5),
 410 .BR hostname (7),
 411 .BR named (8)
 412 .\" .BR resolv+ (8)