1GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
2
6 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
7 h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostby‐
8 name2_r, gethostbyname_r, gethostent_r - get network host entry
9
11 #include <netdb.h>
12 extern int h_errno;
13 struct hostent *gethostbyname(const char *name);
15 #include <sys/socket.h> /* for AF_INET */
17 struct hostent *gethostbyaddr(const void *addr,
18 socklen_t len, int type);
19 void sethostent(int stayopen);
21 void endhostent(void);
23 void herror(const char *s);
25 const char *hstrerror(int err);
27 /* System V/POSIX extension */
29 struct hostent *gethostent(void);
30 /* GNU extensions */
32 struct hostent *gethostbyname2(const char *name, int af);
33 int gethostent_r(
35 struct hostent *ret, char *buf, size_t buflen,
36 struct hostent **result, int *h_errnop);
37 int gethostbyaddr_r(const void *addr, socklen_t len, int type,
39 struct hostent *ret, char *buf, size_t buflen,
40 struct hostent **result, int *h_errnop);
41 int gethostbyname_r(const char *name,
43 struct hostent *ret, char *buf, size_t buflen,
44 struct hostent **result, int *h_errnop);
45 int gethostbyname2_r(const char *name, int af,
47 struct hostent *ret, char *buf, size_t buflen,
48 struct hostent **result, int *h_errnop);
49 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
51 gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
53 gethostbyname2_r(): _BSD_SOURCE || _SVID_SOURCE
54
56 The gethostbyname*() and gethostbyaddr*() functions are obsolete.
57 Applications should use getaddrinfo(3) and getnameinfo(3) instead.
58 The gethostbyname() function returns a structure of type hostent for
60 the given host name. Here name is either a hostname, or an IPv4
61 address in standard dot notation (as for inet_addr(3)), or an IPv6
62 address in colon (and possibly dot) notation. (See RFC 1884 for the
63 description of IPv6 addresses.) If name is an IPv4 or IPv6 address, no
64 lookup is performed and gethostbyname() simply copies name into the
65 h_name field and its struct in_addr equivalent into the h_addr_list[0]
66 field of the returned hostent structure. If name doesn't end in a dot
67 and the environment variable HOSTALIASES is set, the alias file pointed
68 to by HOSTALIASES will first be searched for name (see hostname(7) for
69 the file format). The current domain and its parents are searched
70 unless name ends in a dot.
71 The gethostbyaddr() function returns a structure of type hostent for
73 the given host address addr of length len and address type type. Valid
74 address types are AF_INET and AF_INET6. The host address argument is a
75 pointer to a struct of a type depending on the address type, for exam‐
76 ple a struct in_addr * (probably obtained via a call to inet_addr(3))
77 for address type AF_INET.
78 The sethostent() function specifies, if stayopen is true (1), that a
80 connected TCP socket should be used for the name server queries and
81 that the connection should remain open during successive queries. Oth‐
82 erwise, name server queries will use UDP datagrams.
83 The endhostent() function ends the use of a TCP connection for name
85 server queries.
86 The (obsolete) herror() function prints the error message associated
88 with the current value of h_errno on stderr.
89 The (obsolete) hstrerror() function takes an error number (typically
91 h_errno) and returns the corresponding message string.
92 The domain name queries carried out by gethostbyname() and gethost‐
94 byaddr() use a combination of any or all of the name server named(8), a
95 broken out line from /etc/hosts, and the Network Information Service
96 (NIS or YP), depending upon the contents of the order line in
97 /etc/host.conf. The default action is to query named(8), followed by
98 /etc/hosts.
99 The hostent structure is defined in <netdb.h> as follows:
101 struct hostent {
103 char *h_name; /* official name of host */
104 char **h_aliases; /* alias list */
105 int h_addrtype; /* host address type */
106 int h_length; /* length of address */
107 char **h_addr_list; /* list of addresses */
108 }
109 #define h_addr h_addr_list[0] /* for backward compatibility */
110 The members of the hostent structure are:
112 h_name The official name of the host.
114 h_aliases
116 An array of alternative names for the host, terminated by a NULL
117 pointer.
118 h_addrtype
120 The type of address; always AF_INET or AF_INET6 at present.
121 h_length
123 The length of the address in bytes.
124 h_addr_list
126 An array of pointers to network addresses for the host (in net‐
127 work byte order), terminated by a NULL pointer.
128 h_addr The first address in h_addr_list for backward compatibility.
130
132 The gethostbyname() and gethostbyaddr() functions return the hostent
133 structure or a NULL pointer if an error occurs. On error, the h_errno
134 variable holds an error number. When non-NULL, the return value may
135 point at static data, see the notes below.
136
138 The variable h_errno can have the following values:
139 HOST_NOT_FOUND
141 The specified host is unknown.
142 NO_ADDRESS or NO_DATA
144 The requested name is valid but does not have an IP address.
145 NO_RECOVERY
147 A non-recoverable name server error occurred.
148 TRY_AGAIN
150 A temporary error occurred on an authoritative name server. Try
151 again later.
152
154 /etc/host.conf
155 resolver configuration file
156 /etc/hosts
158 host database file
159 /etc/nsswitch.conf
161 name service switch configuration
162
164 POSIX.1-2001 specifies gethostbyname(), gethostbyaddr(), sethostent(),
165 endhostent(), gethostent(), and h_errno; gethostbyname(), gethost‐
166 byaddr(), and h_errno are marked obsolescent in that standard.
167 POSIX.1-2008 removes the specifications of gethostbyname(), gethost‐
168 byaddr(), and h_errno, recommending the use of getaddrinfo(3) and get‐
169 nameinfo(3) instead.
170
172 The functions gethostbyname() and gethostbyaddr() may return pointers
173 to static data, which may be overwritten by later calls. Copying the
174 struct hostent does not suffice, since it contains pointers; a deep
175 copy is required.
176 In the original BSD implementation the len argument of gethostbyname()
178 was an int. The SUSv2 standard is buggy and declares the len argument
179 of gethostbyaddr() to be of type size_t. (That is wrong, because it
180 has to be int, and size_t is not. POSIX.1-2001 makes it socklen_t,
181 which is OK.) See also accept(2).
182 The BSD prototype for gethostbyaddr() uses const char * for the first
184 argument.
185 System V/POSIX Extension
187 POSIX requires the gethostent() call, that should return the next entry
188 in the host data base. When using DNS/BIND this does not make much
189 sense, but it may be reasonable if the host data base is a file that
190 can be read line by line. On many systems a routine of this name reads
191 from the file /etc/hosts. It may be available only when the library
192 was built without DNS support. The glibc version will ignore ipv6
193 entries. This function is not reentrant, and glibc adds a reentrant
194 version gethostent_r().
195 GNU Extensions
197 Glibc2 also has a gethostbyname2() that works like gethostbyname(), but
198 permits to specify the address family to which the address must belong.
199 Glibc2 also has reentrant versions gethostent_r(), gethostbyaddr_r(),
201 gethostbyname_r() and gethostbyname2_r(). The caller supplies a hos‐
202 tent structure ret which will be filled in on success, and a temporary
203 work buffer buf of size buflen. After the call, result will point to
204 the result on success. In case of an error or if no entry is found
205 result will be NULL. The functions return 0 on success and a non-zero
206 error number on failure. In addition to the errors returned by the
207 non-reentrant versions of these functions, if buf is too small, the
208 functions will return ERANGE, and the call should be retried with a
209 larger buffer. The global variable h_errno is not modified, but the
210 address of a variable in which to store error numbers is passed in
211 h_errnop.
212
214 gethostbyname() does not recognize components of a dotted IPv4 address
215 string that are expressed in hexadecimal.
216
218 getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3),
219 resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)
220
222 This page is part of release 3.22 of the Linux man-pages project. A
223 description of the project, and information about reporting bugs, can
224 be found at http://www.kernel.org/doc/man-pages/.
225 2009-03-15 GETHOSTBYNAME(3)