1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" References consulted:
26 .\" Linux libc source code
27 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
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
38 .TH GETHOSTBYNAME 3 2014-03-11 "" "Linux Programmer's Manual"
40 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
44 gethostbyname2, gethostbyname2_r, gethostbyname_r,
45 gethostent_r \- get network host entry
49 .B extern int h_errno;
51 .BI "struct hostent *gethostbyname(const char *" name );
53 .BR "#include <sys/socket.h>" " /* for AF_INET */"
54 .BI "struct hostent *gethostbyaddr(const void *" addr ,
55 .BI " socklen_t " len ", int " type );
57 .BI "void sethostent(int " stayopen );
59 .B void endhostent(void);
61 .BI "void herror(const char *" s );
63 .BI "const char *hstrerror(int " err );
65 /* System V/POSIX extension */
67 .B struct hostent *gethostent(void);
71 .BI "struct hostent *gethostbyname2(const char *" name ", int " af );
73 .B "int gethostent_r("
74 .BI " struct hostent *" ret ", char *" buf ", size_t " buflen ,
75 .BI " struct hostent **" result ", int *" h_errnop );
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 );
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 );
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 );
91 Feature Test Macro Requirements for glibc (see
92 .BR feature_test_macros (7)):
97 .BR gethostbyname2 (),
99 .BR gethostbyaddr_r (),
100 .BR gethostbyname_r (),
101 .BR gethostbyname2_r ():
103 _BSD_SOURCE || _SVID_SOURCE
111 _BSD_SOURCE || _SVID_SOURCE
121 _BSD_SOURCE || _SVID_SOURCE ||
122 (_POSIX_C_SOURCE < 200809L && _XOPEN_SOURCE < 700)
131 .BR gethostbyname* (),
132 .BR gethostbyaddr* (),
136 functions are obsolete.
137 Applications should use
146 function returns a structure of type
152 is either a hostname, or an IPv4 address in standard dot notation (as for
154 or an IPv6 address in colon (and possibly dot) notation.
155 (See RFC\ 1884 for the description of IPv6 addresses.)
158 is an IPv4 or IPv6 address, no lookup is performed and
168 field of the returned
173 doesn't end in a dot and the environment variable
175 is set, the alias file pointed to by
177 will first be searched for
181 for the file format).
182 The current domain and its parents are searched unless \fIname\fP
187 function returns a structure of type \fIhostent\fP
188 for the given host address \fIaddr\fP of length \fIlen\fP and address type
190 Valid address types are
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
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.
210 function ends the use of a TCP connection for name
215 function prints the error message associated
216 with the current value of \fIh_errno\fP on \fIstderr\fP.
220 function takes an error number
221 (typically \fIh_errno\fP) and returns the corresponding message string.
223 The domain name queries carried out by
227 use a combination of any or all of the name server
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
234 .\" .BR resolv+ (8)).
235 The default action is to query
240 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
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 */
252 #define h_addr h_addr_list[0] /* for backward compatibility */
256 The members of the \fIhostent\fP structure are:
259 The official name of the host.
262 An array of alternative names for the host, terminated by a null pointer.
265 The type of address; always
272 The length of the address in bytes.
275 An array of pointers to network addresses for the host (in network byte
276 order), terminated by a null pointer.
279 The first address in \fIh_addr_list\fP for backward compatibility.
287 structure or a null pointer if an error occurs.
290 variable holds an error number.
291 When non-NULL, the return value may point at static data, see the notes below.
293 The variable \fIh_errno\fP can have the following values:
296 The specified host is unknown.
298 .BR NO_ADDRESS " or " NO_DATA
299 The requested name is valid but does not have an IP address.
302 A nonrecoverable name server error occurred.
305 A temporary error occurred on an authoritative name server.
310 resolver configuration file
315 .I /etc/nsswitch.conf
316 name service switch configuration
318 POSIX.1-2001 specifies
319 .BR gethostbyname (),
320 .BR gethostbyaddr (),
326 .BR gethostbyname (),
327 .BR gethostbyaddr (),
330 are marked obsolescent in that standard.
331 POSIX.1-2008 removes the specifications of
332 .BR gethostbyname (),
333 .BR gethostbyaddr (),
336 recommending the use of
346 may return pointers to static data, which may be overwritten by
350 does not suffice, since it contains pointers; a deep copy is required.
352 In the original BSD implementation the
359 The SUSv2 standard is buggy and declares the
365 (That is wrong, because it has to be
370 POSIX.1-2001 makes it
376 The BSD prototype for
380 for the first argument.
381 .SS System V/POSIX extension
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
388 On many systems a routine of this name reads
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
400 .BR gethostbyname2 ()
402 .BR gethostbyname (),
403 but permits to specify the address family to which the address must belong.
405 Glibc2 also has reentrant versions
407 .BR gethostbyaddr_r (),
408 .BR gethostbyname_r ()
410 .BR gethostbyname2_r ().
411 The caller supplies a
415 which will be filled in on success, and a temporary work buffer
421 will point to the result on success.
423 or if no entry is found
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
430 is too small, the functions will return
432 and the call should be retried with a larger buffer.
435 is not modified, but the address of a variable in which to store error numbers
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
445 .\" .BR getipnodebyaddr (3),
446 .\" .BR getipnodebyname (3),
453 .BR nsswitch.conf (5),