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