1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
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.
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.
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
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" References consulted:
24 .\" Linux libc source code
25 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
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
36 .TH GETHOSTBYNAME 3 2010-10-04 "" "Linux Programmer's Manual"
38 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
42 gethostbyname2, gethostbyname2_r, gethostbyname_r,
43 gethostent_r \- get network host entry
47 .B extern int h_errno;
49 .BI "struct hostent *gethostbyname(const char *" name );
51 .BR "#include <sys/socket.h>" " /* for AF_INET */"
52 .BI "struct hostent *gethostbyaddr(const void *" addr ,
53 .BI " socklen_t " len ", int " type );
55 .BI "void sethostent(int " stayopen );
57 .B void endhostent(void);
59 .BI "void herror(const char *" s );
61 .BI "const char *hstrerror(int " err );
63 /* System V/POSIX extension */
65 .B struct hostent *gethostent(void);
69 .BI "struct hostent *gethostbyname2(const char *" name ", int " af );
71 .B "int gethostent_r("
72 .BI " struct hostent *" ret ", char *" buf ", size_t " buflen ,
73 .BI " struct hostent **" result ", int *" h_errnop );
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 );
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 );
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 );
89 Feature Test Macro Requirements for glibc (see
90 .BR feature_test_macros (7)):
95 .BR gethostbyname2 (),
97 .BR gethostbyaddr_r (),
98 .BR gethostbyname_r (),
99 .BR gethostbyname2_r ():
101 _BSD_SOURCE || _SVID_SOURCE
109 _BSD_SOURCE || _SVID_SOURCE || _GNU_SOURCE
118 .BR gethostbyname* ()
120 .BR gethostbyaddr* ()
121 functions are obsolete.
122 Applications should use
130 function returns a structure of type
136 is either a hostname, or an IPv4 address in standard dot notation (as for
138 or an IPv6 address in colon (and possibly dot) notation.
139 (See RFC\ 1884 for the description of IPv6 addresses.)
142 is an IPv4 or IPv6 address, no lookup is performed and
152 field of the returned
157 doesn't end in a dot and the environment variable
159 is set, the alias file pointed to by
161 will first be searched for
165 for the file format).
166 The current domain and its parents are searched unless \fIname\fP
171 function returns a structure of type \fIhostent\fP
172 for the given host address \fIaddr\fP of length \fIlen\fP and address type
174 Valid address types are
178 The host address argument is a pointer to a struct of a type depending
179 on the address type, for example a \fIstruct in_addr *\fP (probably
180 obtained via a call to
187 function specifies, if \fIstayopen\fP is true (1),
188 that a connected TCP socket should be used for the name server queries and
189 that the connection should remain open during successive queries.
190 Otherwise, name server queries will use UDP datagrams.
194 function ends the use of a TCP connection for name
199 function prints the error message associated
200 with the current value of \fIh_errno\fP on \fIstderr\fP.
204 function takes an error number
205 (typically \fIh_errno\fP) and returns the corresponding message string.
207 The domain name queries carried out by
211 use a combination of any or all of the name server
213 a broken out line from \fI/etc/hosts\fP, and the Network
214 Information Service (NIS or YP), depending upon the contents of the
218 .\" .BR resolv+ (8)).
219 The default action is to query
224 The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
230 char *h_name; /* official name of host */
231 char **h_aliases; /* alias list */
232 int h_addrtype; /* host address type */
233 int h_length; /* length of address */
234 char **h_addr_list; /* list of addresses */
236 #define h_addr h_addr_list[0] /* for backward compatibility */
240 The members of the \fIhostent\fP structure are:
243 The official name of the host.
246 An array of alternative names for the host, terminated by a NULL pointer.
249 The type of address; always
256 The length of the address in bytes.
259 An array of pointers to network addresses for the host (in network byte
260 order), terminated by a NULL pointer.
263 The first address in \fIh_addr_list\fP for backward compatibility.
271 structure or a NULL pointer if an error occurs.
274 variable holds an error number.
275 When non-NULL, the return value may point at static data, see the notes below.
277 The variable \fIh_errno\fP can have the following values:
280 The specified host is unknown.
282 .BR NO_ADDRESS " or " NO_DATA
283 The requested name is valid but does not have an IP address.
286 A nonrecoverable name server error occurred.
289 A temporary error occurred on an authoritative name server.
294 resolver configuration file
299 .I /etc/nsswitch.conf
300 name service switch configuration
302 POSIX.1-2001 specifies
303 .BR gethostbyname (),
304 .BR gethostbyaddr (),
310 .BR gethostbyname (),
311 .BR gethostbyaddr (),
314 are marked obsolescent in that standard.
315 POSIX.1-2008 removes the specifications of
316 .BR gethostbyname (),
317 .BR gethostbyaddr (),
320 recommending the use of
330 may return pointers to static data, which may be overwritten by
334 does not suffice, since it contains pointers; a deep copy is required.
336 In the original BSD implementation the
343 The SUSv2 standard is buggy and declares the
349 (That is wrong, because it has to be
354 POSIX.1-2001 makes it
360 The BSD prototype for
364 for the first argument.
365 .SS "System V/POSIX Extension"
368 call, that should return the next entry in the host data base.
369 When using DNS/BIND this does not make much sense, but it may
370 be reasonable if the host data base is a file that can be read
372 On many systems a routine of this name reads
375 .\" e.g., Linux, FreeBSD, UnixWare, HP-UX
376 It may be available only when the library was built without DNS support.
377 .\" e.g., FreeBSD, AIX
378 The glibc version will ignore ipv6 entries.
379 This function is not reentrant,
380 and glibc adds a reentrant version
384 .BR gethostbyname2 ()
386 .BR gethostbyname (),
387 but permits to specify the address family to which the address must belong.
389 Glibc2 also has reentrant versions
391 .BR gethostbyaddr_r (),
392 .BR gethostbyname_r ()
394 .BR gethostbyname2_r ().
395 The caller supplies a
399 which will be filled in on success, and a temporary work buffer
405 will point to the result on success.
407 or if no entry is found
410 The functions return 0 on success and a nonzero error number on failure.
411 In addition to the errors returned by the nonreentrant
412 versions of these functions, if
414 is too small, the functions will return
416 and the call should be retried with a larger buffer.
419 is not modified, but the address of a variable in which to store error numbers
424 does not recognize components of a dotted IPv4 address string
425 that are expressed in hexadecimal.
426 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973
429 .\" .BR getipnodebyaddr (3),
430 .\" .BR getipnodebyname (3),
437 .BR nsswitch.conf (5),