1GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
2
6 gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_er‐
7 rno, 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;
14 struct hostent *gethostbyname(const char *name);
16 struct hostent *gethostbyaddr(const void *addr,
17 socklen_t len, int type);
18 void sethostent(int stayopen);
20 void endhostent(void);
21 void herror(const char *s);
23 const char *hstrerror(int err);
24 /* System V/POSIX extension */
26 struct hostent *gethostent(void);
27 /* GNU extensions */
29 struct hostent *gethostbyname2(const char *name, int af);
30 int gethostent_r(struct hostent *restrict ret,
32 char *restrict buf, size_t buflen,
33 struct hostent **restrict result,
34 int *restrict h_errnop);
35 int gethostbyaddr_r(const void *restrict addr, socklen_t len, int type,
37 struct hostent *restrict ret,
38 char *restrict buf, size_t buflen,
39 struct hostent **restrict result,
40 int *restrict h_errnop);
41 int gethostbyname_r(const char *restrict name,
42 struct hostent *restrict ret,
43 char *restrict buf, size_t buflen,
44 struct hostent **restrict result,
45 int *restrict h_errnop);
46 int gethostbyname2_r(const char *restrict name, int af,
47 struct hostent *restrict ret,
48 char *restrict buf, size_t buflen,
49 struct hostent **restrict result,
50 int *restrict h_errnop);
51 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
53 gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
55 gethostbyname2_r():
56 Since glibc 2.19:
57 _DEFAULT_SOURCE
58 Glibc up to and including 2.19:
59 _BSD_SOURCE || _SVID_SOURCE
60 herror(), hstrerror():
62 Since glibc 2.19:
63 _DEFAULT_SOURCE
64 Glibc 2.8 to 2.19:
65 _BSD_SOURCE || _SVID_SOURCE
66 Before glibc 2.8:
67 none
68 h_errno:
70 Since glibc 2.19
71 _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
72 Glibc 2.12 to 2.19:
73 _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
74 Before glibc 2.12:
75 none
76
78 The gethostbyname*(), gethostbyaddr*(), herror(), and hstrerror() func‐
79 tions are obsolete. Applications should use getaddrinfo(3), getname‐
80 info(3), and gai_strerror(3) instead.
81 The gethostbyname() function returns a structure of type hostent for
83 the given host name. Here name is either a hostname or an IPv4 address
84 in standard dot notation (as for inet_addr(3)). If name is an IPv4 ad‐
85 dress, no lookup is performed and gethostbyname() simply copies name
86 into the h_name field and its struct in_addr equivalent into the
87 h_addr_list[0] field of the returned hostent structure. If name
88 doesn't end in a dot and the environment variable HOSTALIASES is set,
89 the alias file pointed to by HOSTALIASES will first be searched for
90 name (see hostname(7) for the file format). The current domain and its
91 parents are searched unless name ends in a dot.
92 The gethostbyaddr() function returns a structure of type hostent for
94 the given host address addr of length len and address type type. Valid
95 address types are AF_INET and AF_INET6 (defined in <sys/socket.h>).
96 The host address argument is a pointer to a struct of a type depending
97 on the address type, for example a struct in_addr * (probably obtained
98 via a call to inet_addr(3)) for address type AF_INET.
99 The sethostent() function specifies, if stayopen is true (1), that a
101 connected TCP socket should be used for the name server queries and
102 that the connection should remain open during successive queries. Oth‐
103 erwise, name server queries will use UDP datagrams.
104 The endhostent() function ends the use of a TCP connection for name
106 server queries.
107 The (obsolete) herror() function prints the error message associated
109 with the current value of h_errno on stderr.
110 The (obsolete) hstrerror() function takes an error number (typically
112 h_errno) and returns the corresponding message string.
113 The domain name queries carried out by gethostbyname() and gethost‐
115 byaddr() rely on the Name Service Switch (nsswitch.conf(5)) configured
116 sources or a local name server (named(8)). The default action is to
117 query the Name Service Switch (nsswitch.conf(5)) configured sources,
118 failing that, a local name server (named(8)).
119 Historical
121 The nsswitch.conf(5) file is the modern way of controlling the order of
122 host lookups.
123 In glibc 2.4 and earlier, the order keyword was used to control the or‐
125 der of host lookups as defined in /etc/host.conf (host.conf(5)).
126 The hostent structure is defined in <netdb.h> as follows:
128 struct hostent {
130 char *h_name; /* official name of host */
131 char **h_aliases; /* alias list */
132 int h_addrtype; /* host address type */
133 int h_length; /* length of address */
134 char **h_addr_list; /* list of addresses */
135 }
136 #define h_addr h_addr_list[0] /* for backward compatibility */
137 The members of the hostent structure are:
139 h_name The official name of the host.
141 h_aliases
143 An array of alternative names for the host, terminated by a null
144 pointer.
145 h_addrtype
147 The type of address; always AF_INET or AF_INET6 at present.
148 h_length
150 The length of the address in bytes.
151 h_addr_list
153 An array of pointers to network addresses for the host (in net‐
154 work byte order), terminated by a null pointer.
155 h_addr The first address in h_addr_list for backward compatibility.
157
159 The gethostbyname() and gethostbyaddr() functions return the hostent
160 structure or a null pointer if an error occurs. On error, the h_errno
161 variable holds an error number. When non-NULL, the return value may
162 point at static data, see the notes below.
163
165 The variable h_errno can have the following values:
166 HOST_NOT_FOUND
168 The specified host is unknown.
169 NO_DATA
171 The requested name is valid but does not have an IP address.
172 Another type of request to the name server for this domain may
173 return an answer. The constant NO_ADDRESS is a synonym for
174 NO_DATA.
175 NO_RECOVERY
177 A nonrecoverable name server error occurred.
178 TRY_AGAIN
180 A temporary error occurred on an authoritative name server. Try
181 again later.
182
184 /etc/host.conf
185 resolver configuration file
186 /etc/hosts
188 host database file
189 /etc/nsswitch.conf
191 name service switch configuration
192
194 For an explanation of the terms used in this section, see at‐
195 tributes(7).
196 ┌───────────────────┬───────────────┬──────────────────────────────────┐
198 │Interface │ Attribute │ Value │
199 ├───────────────────┼───────────────┼──────────────────────────────────┤
200 │gethostbyname() │ Thread safety │ MT-Unsafe race:hostbyname env │
201 │ │ │ locale │
202 ├───────────────────┼───────────────┼──────────────────────────────────┤
203 │gethostbyaddr() │ Thread safety │ MT-Unsafe race:hostbyaddr env │
204 │ │ │ locale │
205 ├───────────────────┼───────────────┼──────────────────────────────────┤
206 │sethostent(), │ Thread safety │ MT-Unsafe race:hostent env │
207 │endhostent(), │ │ locale │
208 │gethostent_r() │ │ │
209 ├───────────────────┼───────────────┼──────────────────────────────────┤
210 │herror(), │ Thread safety │ MT-Safe │
211 │hstrerror() │ │ │
212 ├───────────────────┼───────────────┼──────────────────────────────────┤
213 │gethostent() │ Thread safety │ MT-Unsafe race:hostent │
214 │ │ │ race:hostentbuf env locale │
215 ├───────────────────┼───────────────┼──────────────────────────────────┤
216 │gethostbyname2() │ Thread safety │ MT-Unsafe race:hostbyname2 env │
217 │ │ │ locale │
218 ├───────────────────┼───────────────┼──────────────────────────────────┤
219 │gethostbyaddr_r(), │ Thread safety │ MT-Safe env locale │
220 │gethostbyname_r(), │ │ │
221 │gethostbyname2_r() │ │ │
222 └───────────────────┴───────────────┴──────────────────────────────────┘
223 In the above table, hostent in race:hostent signifies that if any of
224 the functions sethostent(), gethostent(), gethostent_r(), or endhos‐
225 tent() are used in parallel in different threads of a program, then da‐
226 ta races could occur.
227
229 POSIX.1-2001 specifies gethostbyname(), gethostbyaddr(), sethostent(),
230 endhostent(), gethostent(), and h_errno; gethostbyname(), gethostbyad‐
231 dr(), and h_errno are marked obsolescent in that standard.
232 POSIX.1-2008 removes the specifications of gethostbyname(), gethost‐
233 byaddr(), and h_errno, recommending the use of getaddrinfo(3) and get‐
234 nameinfo(3) instead.
235
237 The functions gethostbyname() and gethostbyaddr() may return pointers
238 to static data, which may be overwritten by later calls. Copying the
239 struct hostent does not suffice, since it contains pointers; a deep
240 copy is required.
241 In the original BSD implementation the len argument of gethostbyname()
243 was an int. The SUSv2 standard is buggy and declares the len argument
244 of gethostbyaddr() to be of type size_t. (That is wrong, because it
245 has to be int, and size_t is not. POSIX.1-2001 makes it socklen_t,
246 which is OK.) See also accept(2).
247 The BSD prototype for gethostbyaddr() uses const char * for the first
249 argument.
250 System V/POSIX extension
252 POSIX requires the gethostent() call, which should return the next en‐
253 try in the host data base. When using DNS/BIND this does not make much
254 sense, but it may be reasonable if the host data base is a file that
255 can be read line by line. On many systems, a routine of this name
256 reads from the file /etc/hosts. It may be available only when the li‐
257 brary was built without DNS support. The glibc version will ignore
258 ipv6 entries. This function is not reentrant, and glibc adds a reen‐
259 trant version gethostent_r().
260 GNU extensions
262 Glibc2 also has a gethostbyname2() that works like gethostbyname(), but
263 permits to specify the address family to which the address must belong.
264 Glibc2 also has reentrant versions gethostent_r(), gethostbyaddr_r(),
266 gethostbyname_r(), and gethostbyname2_r(). The caller supplies a hos‐
267 tent structure ret which will be filled in on success, and a temporary
268 work buffer buf of size buflen. After the call, result will point to
269 the result on success. In case of an error or if no entry is found re‐
270 sult will be NULL. The functions return 0 on success and a nonzero er‐
271 ror number on failure. In addition to the errors returned by the non‐
272 reentrant versions of these functions, if buf is too small, the func‐
273 tions will return ERANGE, and the call should be retried with a larger
274 buffer. The global variable h_errno is not modified, but the address
275 of a variable in which to store error numbers is passed in h_errnop.
276
278 gethostbyname() does not recognize components of a dotted IPv4 address
279 string that are expressed in hexadecimal.
280
282 getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3),
283 resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)
284
286 This page is part of release 5.12 of the Linux man-pages project. A
287 description of the project, information about reporting bugs, and the
288 latest version of this page, can be found at
289 https://www.kernel.org/doc/man-pages/.
290 2021-03-22 GETHOSTBYNAME(3)