]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
4 | .\" |
5 | .\" References consulted: | |
6 | .\" Linux libc source code | |
7 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
8 | .\" 386BSD man pages | |
9 | .\" Modified 1993-05-22, David Metcalfe | |
10 | .\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) | |
11 | .\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl) | |
12 | .\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl) | |
13 | .\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl) | |
14 | .\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl) | |
15 | .\" Modified 2002-08-05, Michael Kerrisk | |
16 | .\" Modified 2004-10-31, Andries Brouwer | |
17 | .\" | |
45186a5d | 18 | .TH GETHOSTBYNAME 3 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 19 | .SH NAME |
d302a9a9 | 20 | gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, |
a039244f | 21 | h_errno, |
7fa78155 | 22 | herror, hstrerror, |
1dcf5e2f | 23 | gethostbyaddr_r, |
7fa78155 MK |
24 | gethostbyname2, gethostbyname2_r, gethostbyname_r, |
25 | gethostent_r \- get network host entry | |
42009080 AC |
26 | .SH LIBRARY |
27 | Standard C library | |
28 | .RI ( libc ", " \-lc ) | |
fea681da MK |
29 | .SH SYNOPSIS |
30 | .nf | |
31 | .B #include <netdb.h> | |
15d65653 | 32 | .PP |
fea681da | 33 | .B extern int h_errno; |
68e4db0a | 34 | .PP |
fea681da | 35 | .BI "struct hostent *gethostbyname(const char *" name ); |
e859a67a | 36 | .BI "struct hostent *gethostbyaddr(const void *" addr , |
768cfd1d | 37 | .BI " socklen_t " len ", int " type ); |
68e4db0a | 38 | .PP |
fea681da | 39 | .BI "void sethostent(int " stayopen ); |
fea681da | 40 | .B void endhostent(void); |
68e4db0a | 41 | .PP |
fea681da | 42 | .BI "void herror(const char *" s ); |
fea681da | 43 | .BI "const char *hstrerror(int " err ); |
68e4db0a | 44 | .PP |
80b50848 | 45 | /* System V/POSIX extension */ |
fea681da | 46 | .B struct hostent *gethostent(void); |
68e4db0a | 47 | .PP |
fea681da | 48 | /* GNU extensions */ |
fea681da | 49 | .BI "struct hostent *gethostbyname2(const char *" name ", int " af ); |
68e4db0a | 50 | .PP |
938c8215 AC |
51 | .BI "int gethostent_r(struct hostent *restrict " ret , |
52 | .BI " char *restrict " buf ", size_t " buflen , | |
53 | .BI " struct hostent **restrict " result , | |
54 | .BI " int *restrict " h_errnop ); | |
68e4db0a | 55 | .PP |
938c8215 AC |
56 | .BI "int gethostbyaddr_r(const void *restrict " addr ", socklen_t " len \ |
57 | ", int " type , | |
58 | .BI " struct hostent *restrict " ret , | |
59 | .BI " char *restrict " buf ", size_t " buflen , | |
60 | .BI " struct hostent **restrict " result , | |
61 | .BI " int *restrict " h_errnop ); | |
62 | .BI "int gethostbyname_r(const char *restrict " name , | |
63 | .BI " struct hostent *restrict " ret , | |
64 | .BI " char *restrict " buf ", size_t " buflen , | |
65 | .BI " struct hostent **restrict " result , | |
66 | .BI " int *restrict " h_errnop ); | |
67 | .BI "int gethostbyname2_r(const char *restrict " name ", int " af, | |
68 | .BI " struct hostent *restrict " ret , | |
69 | .BI " char *restrict " buf ", size_t " buflen , | |
70 | .BI " struct hostent **restrict " result , | |
71 | .BI " int *restrict " h_errnop ); | |
fea681da | 72 | .fi |
68e4db0a | 73 | .PP |
d39ad78f | 74 | .RS -4 |
cc4615cc MK |
75 | Feature Test Macro Requirements for glibc (see |
76 | .BR feature_test_macros (7)): | |
d39ad78f | 77 | .RE |
68e4db0a | 78 | .PP |
cc4615cc MK |
79 | .BR gethostbyname2 (), |
80 | .BR gethostent_r (), | |
dd0fee67 | 81 | .BR gethostbyaddr_r (), |
cc4615cc MK |
82 | .BR gethostbyname_r (), |
83 | .BR gethostbyname2_r (): | |
9d2adbae MK |
84 | .nf |
85 | Since glibc 2.19: | |
86 | _DEFAULT_SOURCE | |
87 | Glibc up to and including 2.19: | |
88 | _BSD_SOURCE || _SVID_SOURCE | |
89 | .fi | |
847e0d88 | 90 | .PP |
f87ab547 | 91 | .BR herror (), |
6d80e8c7 | 92 | .BR hstrerror (): |
9d2adbae MK |
93 | .nf |
94 | Since glibc 2.19: | |
95 | _DEFAULT_SOURCE | |
96 | Glibc 2.8 to 2.19: | |
97 | _BSD_SOURCE || _SVID_SOURCE | |
98 | Before glibc 2.8: | |
99 | none | |
100 | .fi | |
847e0d88 | 101 | .PP |
930c9b6d | 102 | .BR h_errno : |
9d2adbae MK |
103 | .nf |
104 | Since glibc 2.19 | |
105 | _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L | |
106 | Glibc 2.12 to 2.19: | |
107 | _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L | |
108 | Before glibc 2.12: | |
109 | none | |
110 | .fi | |
fea681da | 111 | .SH DESCRIPTION |
aa966d08 | 112 | The |
7d0ec5b6 MK |
113 | .BR gethostbyname* (), |
114 | .BR gethostbyaddr* (), | |
115 | .BR herror (), | |
aa966d08 | 116 | and |
7d0ec5b6 | 117 | .BR hstrerror () |
aa966d08 | 118 | functions are obsolete. |
567e8a7f | 119 | Applications should use |
7d0ec5b6 MK |
120 | .BR getaddrinfo (3), |
121 | .BR getnameinfo (3), | |
567e8a7f | 122 | and |
7d0ec5b6 | 123 | .BR gai_strerror (3) |
567e8a7f | 124 | instead. |
847e0d88 | 125 | .PP |
fea681da MK |
126 | The |
127 | .BR gethostbyname () | |
128 | function returns a structure of type | |
129 | .I hostent | |
130 | for the given host | |
131 | .IR name . | |
132 | Here | |
133 | .I name | |
0b8a39ad MK |
134 | is either a hostname or an IPv4 address in standard dot notation (as for |
135 | .BR inet_addr (3)). | |
fea681da MK |
136 | If |
137 | .I name | |
0b8a39ad | 138 | is an IPv4 address, no lookup is performed and |
fea681da MK |
139 | .BR gethostbyname () |
140 | simply copies | |
141 | .I name | |
142 | into the | |
143 | .I h_name | |
144 | field and its | |
145 | .I struct in_addr | |
146 | equivalent into the | |
147 | .I h_addr_list[0] | |
148 | field of the returned | |
149 | .I hostent | |
150 | structure. | |
151 | If | |
152 | .I name | |
153 | doesn't end in a dot and the environment variable | |
154 | .B HOSTALIASES | |
155 | is set, the alias file pointed to by | |
156 | .B HOSTALIASES | |
157 | will first be searched for | |
158 | .I name | |
159 | (see | |
160 | .BR hostname (7) | |
161 | for the file format). | |
162 | The current domain and its parents are searched unless \fIname\fP | |
163 | ends in a dot. | |
164 | .PP | |
60a90ecd MK |
165 | The |
166 | .BR gethostbyaddr () | |
167 | function returns a structure of type \fIhostent\fP | |
fea681da | 168 | for the given host address \fIaddr\fP of length \fIlen\fP and address type |
c13182ef MK |
169 | \fItype\fP. |
170 | Valid address types are | |
fea681da MK |
171 | .B AF_INET |
172 | and | |
1ae6b2c7 | 173 | .B AF_INET6 |
742694e9 MK |
174 | (defined in |
175 | .IR <sys/socket.h> ). | |
fea681da | 176 | The host address argument is a pointer to a struct of a type depending |
89f9f5b2 | 177 | on the address type, for example a \fIstruct in_addr *\fP (probably |
988db661 | 178 | obtained via a call to |
d9c1ae64 | 179 | .BR inet_addr (3)) |
2f0af33b MK |
180 | for address type |
181 | .BR AF_INET . | |
fea681da | 182 | .PP |
60a90ecd MK |
183 | The |
184 | .BR sethostent () | |
185 | function specifies, if \fIstayopen\fP is true (1), | |
c13182ef MK |
186 | that a connected TCP socket should be used for the name server queries and |
187 | that the connection should remain open during successive queries. | |
188 | Otherwise, name server queries will use UDP datagrams. | |
fea681da | 189 | .PP |
60a90ecd MK |
190 | The |
191 | .BR endhostent () | |
192 | function ends the use of a TCP connection for name | |
fea681da MK |
193 | server queries. |
194 | .PP | |
60a90ecd MK |
195 | The (obsolete) |
196 | .BR herror () | |
197 | function prints the error message associated | |
ce2801d0 | 198 | with the current value of \fIh_errno\fP on \fIstderr\fP. |
fea681da | 199 | .PP |
60a90ecd MK |
200 | The (obsolete) |
201 | .BR hstrerror () | |
202 | function takes an error number | |
fea681da MK |
203 | (typically \fIh_errno\fP) and returns the corresponding message string. |
204 | .PP | |
60a90ecd MK |
205 | The domain name queries carried out by |
206 | .BR gethostbyname () | |
207 | and | |
208 | .BR gethostbyaddr () | |
923d125a | 209 | rely on the Name Service Switch |
0fe4c79a | 210 | .RB ( nsswitch.conf (5)) |
923d125a CD |
211 | configured sources or a local name server |
212 | .RB ( named (8)). | |
81d6e51d | 213 | The default action is to query the Name Service Switch |
3c320453 | 214 | .RB ( nsswitch.conf (5)) |
923d125a | 215 | configured sources, failing that, a local name server |
0fe4c79a | 216 | .RB ( named (8)). |
787dd4ad | 217 | .\" |
923d125a CD |
218 | .SS Historical |
219 | The | |
220 | .BR nsswitch.conf (5) | |
221 | file is the modern way of controlling the order of host lookups. | |
222 | .PP | |
223 | In glibc 2.4 and earlier, the | |
224 | .I order | |
225 | keyword was used to control the order of host lookups as defined in | |
1ae6b2c7 | 226 | .I /etc/host.conf |
beb9356f | 227 | .RB ( host.conf (5)). |
847e0d88 | 228 | .PP |
fea681da | 229 | The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows: |
51f5698d | 230 | .PP |
a08ea57c | 231 | .in +4n |
b8302363 | 232 | .EX |
fea681da | 233 | struct hostent { |
b9f02710 MK |
234 | char *h_name; /* official name of host */ |
235 | char **h_aliases; /* alias list */ | |
236 | int h_addrtype; /* host address type */ | |
237 | int h_length; /* length of address */ | |
238 | char **h_addr_list; /* list of addresses */ | |
fea681da | 239 | } |
b9f02710 | 240 | #define h_addr h_addr_list[0] /* for backward compatibility */ |
b8302363 | 241 | .EE |
a08ea57c | 242 | .in |
fea681da MK |
243 | .PP |
244 | The members of the \fIhostent\fP structure are: | |
245 | .TP | |
246 | .I h_name | |
247 | The official name of the host. | |
248 | .TP | |
249 | .I h_aliases | |
b437fdd9 | 250 | An array of alternative names for the host, terminated by a null pointer. |
fea681da MK |
251 | .TP |
252 | .I h_addrtype | |
253 | The type of address; always | |
254 | .B AF_INET | |
255 | or | |
256 | .B AF_INET6 | |
257 | at present. | |
258 | .TP | |
259 | .I h_length | |
260 | The length of the address in bytes. | |
261 | .TP | |
262 | .I h_addr_list | |
28d88c17 | 263 | An array of pointers to network addresses for the host (in network byte |
b437fdd9 | 264 | order), terminated by a null pointer. |
fea681da MK |
265 | .TP |
266 | .I h_addr | |
267 | The first address in \fIh_addr_list\fP for backward compatibility. | |
47297adb | 268 | .SH RETURN VALUE |
fea681da MK |
269 | The |
270 | .BR gethostbyname () | |
271 | and | |
63aa9df0 | 272 | .BR gethostbyaddr () |
fea681da MK |
273 | functions return the |
274 | .I hostent | |
b437fdd9 | 275 | structure or a null pointer if an error occurs. |
c13182ef | 276 | On error, the |
fea681da MK |
277 | .I h_errno |
278 | variable holds an error number. | |
279 | When non-NULL, the return value may point at static data, see the notes below. | |
280 | .SH ERRORS | |
281 | The variable \fIh_errno\fP can have the following values: | |
282 | .TP | |
283 | .B HOST_NOT_FOUND | |
284 | The specified host is unknown. | |
285 | .TP | |
1ae6b2c7 | 286 | .B NO_DATA |
fea681da | 287 | The requested name is valid but does not have an IP address. |
ae9b41ac MK |
288 | Another type of request to the name server for this domain |
289 | may return an answer. | |
491e87a5 | 290 | The constant |
1ae6b2c7 | 291 | .B NO_ADDRESS |
491e87a5 MK |
292 | is a synonym for |
293 | .BR NO_DATA . | |
fea681da MK |
294 | .TP |
295 | .B NO_RECOVERY | |
b28f6e56 | 296 | A nonrecoverable name server error occurred. |
fea681da MK |
297 | .TP |
298 | .B TRY_AGAIN | |
c13182ef MK |
299 | A temporary error occurred on an authoritative name server. |
300 | Try again later. | |
fea681da MK |
301 | .SH FILES |
302 | .TP | |
303 | .I /etc/host.conf | |
304 | resolver configuration file | |
305 | .TP | |
306 | .I /etc/hosts | |
307 | host database file | |
24268a72 MK |
308 | .TP |
309 | .I /etc/nsswitch.conf | |
310 | name service switch configuration | |
c7bd50f1 ZL |
311 | .SH ATTRIBUTES |
312 | For an explanation of the terms used in this section, see | |
313 | .BR attributes (7). | |
c466875e MK |
314 | .ad l |
315 | .nh | |
c7bd50f1 ZL |
316 | .TS |
317 | allbox; | |
c466875e | 318 | lb lb lbx |
c7bd50f1 ZL |
319 | l l l. |
320 | Interface Attribute Value | |
321 | T{ | |
322 | .BR gethostbyname () | |
323 | T} Thread safety T{ | |
324 | MT-Unsafe race:hostbyname env | |
c7bd50f1 ZL |
325 | locale |
326 | T} | |
327 | T{ | |
328 | .BR gethostbyaddr () | |
329 | T} Thread safety T{ | |
330 | MT-Unsafe race:hostbyaddr env | |
c7bd50f1 ZL |
331 | locale |
332 | T} | |
333 | T{ | |
334 | .BR sethostent (), | |
c7bd50f1 | 335 | .BR endhostent (), |
c7bd50f1 ZL |
336 | .BR gethostent_r () |
337 | T} Thread safety T{ | |
338 | MT-Unsafe race:hostent env | |
c7bd50f1 ZL |
339 | locale |
340 | T} | |
341 | T{ | |
342 | .BR herror (), | |
c7bd50f1 ZL |
343 | .BR hstrerror () |
344 | T} Thread safety MT-Safe | |
345 | T{ | |
346 | .BR gethostent () | |
347 | T} Thread safety T{ | |
348 | MT-Unsafe race:hostent | |
c7bd50f1 ZL |
349 | race:hostentbuf env locale |
350 | T} | |
351 | T{ | |
352 | .BR gethostbyname2 () | |
353 | T} Thread safety T{ | |
354 | MT-Unsafe race:hostbyname2 | |
c7bd50f1 ZL |
355 | env locale |
356 | T} | |
357 | T{ | |
358 | .BR gethostbyaddr_r (), | |
359 | .BR gethostbyname_r (), | |
360 | .BR gethostbyname2_r () | |
361 | T} Thread safety MT-Safe env locale | |
362 | .TE | |
c466875e MK |
363 | .hy |
364 | .ad | |
847e0d88 | 365 | .sp 1 |
c7bd50f1 ZL |
366 | In the above table, |
367 | .I hostent | |
368 | in | |
369 | .I race:hostent | |
370 | signifies that if any of the functions | |
a39dc3ee MK |
371 | .BR sethostent (), |
372 | .BR gethostent (), | |
373 | .BR gethostent_r (), | |
c7bd50f1 | 374 | or |
a39dc3ee | 375 | .BR endhostent () |
c7bd50f1 ZL |
376 | are used in parallel in different threads of a program, |
377 | then data races could occur. | |
3113c7f3 | 378 | .SH STANDARDS |
12a1a9e7 MK |
379 | POSIX.1-2001 specifies |
380 | .BR gethostbyname (), | |
381 | .BR gethostbyaddr (), | |
382 | .BR sethostent (), | |
383 | .BR endhostent (), | |
384 | .BR gethostent (), | |
385 | and | |
e47fa14c MK |
386 | .IR h_errno ; |
387 | .BR gethostbyname (), | |
388 | .BR gethostbyaddr (), | |
389 | and | |
1ae6b2c7 | 390 | .I h_errno |
e47fa14c | 391 | are marked obsolescent in that standard. |
381c50fd MK |
392 | POSIX.1-2008 removes the specifications of |
393 | .BR gethostbyname (), | |
394 | .BR gethostbyaddr (), | |
395 | and | |
aeb2174a MK |
396 | .IR h_errno , |
397 | recommending the use of | |
398 | .BR getaddrinfo (3) | |
399 | and | |
400 | .BR getnameinfo (3) | |
401 | instead. | |
8af1ba10 MK |
402 | .SH NOTES |
403 | The functions | |
404 | .BR gethostbyname () | |
405 | and | |
406 | .BR gethostbyaddr () | |
407 | may return pointers to static data, which may be overwritten by | |
408 | later calls. | |
409 | Copying the | |
410 | .I struct hostent | |
411 | does not suffice, since it contains pointers; a deep copy is required. | |
dd3568a1 | 412 | .PP |
988db661 | 413 | In the original BSD implementation the |
f9ee70bd MK |
414 | .I len |
415 | argument | |
988db661 | 416 | of |
f9ee70bd MK |
417 | .BR gethostbyname () |
418 | was an | |
419 | .IR int . | |
420 | The SUSv2 standard is buggy and declares the | |
8af1ba10 | 421 | .I len |
c4bb193f | 422 | argument of |
8af1ba10 MK |
423 | .BR gethostbyaddr () |
424 | to be of type | |
425 | .IR size_t . | |
426 | (That is wrong, because it has to be | |
427 | .IR int , | |
428 | and | |
429 | .I size_t | |
430 | is not. | |
431 | POSIX.1-2001 makes it | |
432 | .IR socklen_t , | |
433 | which is OK.) | |
f9ee70bd MK |
434 | See also |
435 | .BR accept (2). | |
dd3568a1 | 436 | .PP |
8af1ba10 MK |
437 | The BSD prototype for |
438 | .BR gethostbyaddr () | |
439 | uses | |
5049da5b | 440 | .I "const char\ *" |
8af1ba10 | 441 | for the first argument. |
73d8cece | 442 | .SS System V/POSIX extension |
fea681da MK |
443 | POSIX requires the |
444 | .BR gethostent () | |
7f325581 | 445 | call, which should return the next entry in the host data base. |
fea681da MK |
446 | When using DNS/BIND this does not make much sense, but it may |
447 | be reasonable if the host data base is a file that can be read | |
c13182ef | 448 | line by line. |
7f325581 | 449 | On many systems, a routine of this name reads |
fea681da MK |
450 | from the file |
451 | .IR /etc/hosts . | |
1f409d5d | 452 | .\" e.g., Linux, FreeBSD, UnixWare, HP-UX |
fea681da | 453 | It may be available only when the library was built without DNS support. |
75b94dc3 | 454 | .\" e.g., FreeBSD, AIX |
c13182ef MK |
455 | The glibc version will ignore ipv6 entries. |
456 | This function is not reentrant, | |
fea681da MK |
457 | and glibc adds a reentrant version |
458 | .BR gethostent_r (). | |
73d8cece | 459 | .SS GNU extensions |
fea681da | 460 | Glibc2 also has a |
63aa9df0 | 461 | .BR gethostbyname2 () |
fea681da | 462 | that works like |
63aa9df0 | 463 | .BR gethostbyname (), |
fea681da | 464 | but permits to specify the address family to which the address must belong. |
dd3568a1 | 465 | .PP |
fea681da | 466 | Glibc2 also has reentrant versions |
dd0fee67 MK |
467 | .BR gethostent_r (), |
468 | .BR gethostbyaddr_r (), | |
d556548b | 469 | .BR gethostbyname_r (), |
fea681da | 470 | and |
63aa9df0 | 471 | .BR gethostbyname2_r (). |
635e8d5a MK |
472 | The caller supplies a |
473 | .I hostent | |
474 | structure | |
dd0fee67 | 475 | .I ret |
635e8d5a | 476 | which will be filled in on success, and a temporary work buffer |
fea681da | 477 | .I buf |
dd0fee67 | 478 | of size |
fea681da | 479 | .IR buflen . |
dd0fee67 MK |
480 | After the call, |
481 | .I result | |
20523df7 MK |
482 | will point to the result on success. |
483 | In case of an error | |
dd0fee67 MK |
484 | or if no entry is found |
485 | .I result | |
635e8d5a | 486 | will be NULL. |
c7094399 | 487 | The functions return 0 on success and a nonzero error number on failure. |
54d75d6c | 488 | In addition to the errors returned by the nonreentrant |
dd0fee67 MK |
489 | versions of these functions, if |
490 | .I buf | |
491 | is too small, the functions will return | |
492 | .BR ERANGE , | |
493 | and the call should be retried with a larger buffer. | |
494 | The global variable | |
fea681da | 495 | .I h_errno |
dd0fee67 | 496 | is not modified, but the address of a variable in which to store error numbers |
fea681da MK |
497 | is passed in |
498 | .IR h_errnop . | |
444aa1ce MK |
499 | .SH BUGS |
500 | .BR gethostbyname () | |
501 | does not recognize components of a dotted IPv4 address string | |
502 | that are expressed in hexadecimal. | |
503 | .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973 | |
47297adb | 504 | .SH SEE ALSO |
fea681da | 505 | .BR getaddrinfo (3), |
652abd33 MK |
506 | .\" .BR getipnodebyaddr (3), |
507 | .\" .BR getipnodebyname (3), | |
fea681da | 508 | .BR getnameinfo (3), |
444aa1ce | 509 | .BR inet (3), |
fea681da MK |
510 | .BR inet_ntop (3), |
511 | .BR inet_pton (3), | |
512 | .BR resolver (3), | |
513 | .BR hosts (5), | |
24268a72 | 514 | .BR nsswitch.conf (5), |
fea681da | 515 | .BR hostname (7), |
24268a72 MK |
516 | .BR named (8) |
517 | .\" .BR resolv+ (8) |