]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
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. | |
6 | .\" | |
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. | |
c13182ef | 11 | .\" |
fea681da MK |
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 | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" References consulted: | |
24 | .\" Linux libc source code | |
25 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
26 | .\" 386BSD man pages | |
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 | |
35 | .\" | |
aa966d08 | 36 | .TH GETHOSTBYNAME 3 2008-08-18 "" "Linux Programmer's Manual" |
fea681da | 37 | .SH NAME |
d302a9a9 | 38 | gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, |
a039244f | 39 | h_errno, |
7fa78155 | 40 | herror, hstrerror, |
1dcf5e2f | 41 | gethostbyaddr_r, |
7fa78155 MK |
42 | gethostbyname2, gethostbyname2_r, gethostbyname_r, |
43 | gethostent_r \- get network host entry | |
fea681da MK |
44 | .SH SYNOPSIS |
45 | .nf | |
46 | .B #include <netdb.h> | |
47 | .B extern int h_errno; | |
48 | .sp | |
49 | .BI "struct hostent *gethostbyname(const char *" name ); | |
50 | .sp | |
51 | .BR "#include <sys/socket.h>" " /* for AF_INET */" | |
e859a67a | 52 | .BI "struct hostent *gethostbyaddr(const void *" addr , |
768cfd1d | 53 | .BI " socklen_t " len ", int " type ); |
fea681da MK |
54 | .sp |
55 | .BI "void sethostent(int " stayopen ); | |
56 | .sp | |
57 | .B void endhostent(void); | |
58 | .sp | |
59 | .BI "void herror(const char *" s ); | |
60 | .sp | |
61 | .BI "const char *hstrerror(int " err ); | |
b9f02710 | 62 | .sp |
80b50848 | 63 | /* System V/POSIX extension */ |
fea681da MK |
64 | .br |
65 | .B struct hostent *gethostent(void); | |
b9f02710 | 66 | .sp |
fea681da MK |
67 | /* GNU extensions */ |
68 | .br | |
69 | .BI "struct hostent *gethostbyname2(const char *" name ", int " af ); | |
70 | .sp | |
0daa9e92 | 71 | .B "int gethostent_r(" |
b9f02710 MK |
72 | .BI " struct hostent *" ret ", char *" buf ", size_t " buflen , |
73 | .BI " struct hostent **" result ", int *" h_errnop ); | |
fea681da | 74 | .sp |
dd0fee67 MK |
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 ); | |
78 | .sp | |
fea681da | 79 | .BI "int gethostbyname_r(const char *" name , |
b9f02710 MK |
80 | .BI " struct hostent *" ret ", char *" buf ", size_t " buflen , |
81 | .BI " struct hostent **" result ", int *" h_errnop ); | |
fea681da MK |
82 | .sp |
83 | .BI "int gethostbyname2_r(const char *" name ", int " af, | |
b9f02710 MK |
84 | .BI " struct hostent *" ret ", char *" buf ", size_t " buflen , |
85 | .BI " struct hostent **" result ", int *" h_errnop ); | |
fea681da | 86 | .fi |
cc4615cc MK |
87 | .sp |
88 | .in -4n | |
89 | Feature Test Macro Requirements for glibc (see | |
90 | .BR feature_test_macros (7)): | |
91 | .in | |
92 | .sp | |
93 | .ad l | |
94 | .BR gethostbyname2 (), | |
95 | .BR gethostent_r (), | |
dd0fee67 | 96 | .BR gethostbyaddr_r (), |
cc4615cc MK |
97 | .BR gethostbyname_r (), |
98 | .BR gethostbyname2_r (): | |
99 | _BSD_SOURCE || _SVID_SOURCE | |
100 | .ad b | |
fea681da | 101 | .SH DESCRIPTION |
aa966d08 MK |
102 | The |
103 | .BR gethostbyname* () | |
104 | and | |
105 | .BR gethostbyaddr* () | |
106 | functions are obsolete. | |
567e8a7f MK |
107 | Applications should use |
108 | .BR getaddrinfo (3) | |
109 | and | |
110 | .BR getnameinfo (3) | |
111 | instead. | |
112 | ||
fea681da MK |
113 | The |
114 | .BR gethostbyname () | |
115 | function returns a structure of type | |
116 | .I hostent | |
117 | for the given host | |
118 | .IR name . | |
119 | Here | |
120 | .I name | |
ddaec46d | 121 | is either a hostname, or an IPv4 address in standard dot notation (as for |
444aa1ce | 122 | .BR inet_addr (3)), |
fea681da | 123 | or an IPv6 address in colon (and possibly dot) notation. |
331da7c3 | 124 | (See RFC\ 1884 for the description of IPv6 addresses.) |
fea681da MK |
125 | If |
126 | .I name | |
127 | is an IPv4 or IPv6 address, no lookup is performed and | |
128 | .BR gethostbyname () | |
129 | simply copies | |
130 | .I name | |
131 | into the | |
132 | .I h_name | |
133 | field and its | |
134 | .I struct in_addr | |
135 | equivalent into the | |
136 | .I h_addr_list[0] | |
137 | field of the returned | |
138 | .I hostent | |
139 | structure. | |
140 | If | |
141 | .I name | |
142 | doesn't end in a dot and the environment variable | |
143 | .B HOSTALIASES | |
144 | is set, the alias file pointed to by | |
145 | .B HOSTALIASES | |
146 | will first be searched for | |
147 | .I name | |
148 | (see | |
149 | .BR hostname (7) | |
150 | for the file format). | |
151 | The current domain and its parents are searched unless \fIname\fP | |
152 | ends in a dot. | |
153 | .PP | |
60a90ecd MK |
154 | The |
155 | .BR gethostbyaddr () | |
156 | function returns a structure of type \fIhostent\fP | |
fea681da | 157 | for the given host address \fIaddr\fP of length \fIlen\fP and address type |
c13182ef MK |
158 | \fItype\fP. |
159 | Valid address types are | |
fea681da MK |
160 | .B AF_INET |
161 | and | |
162 | .BR AF_INET6 . | |
163 | The host address argument is a pointer to a struct of a type depending | |
89f9f5b2 | 164 | on the address type, for example a \fIstruct in_addr *\fP (probably |
988db661 | 165 | obtained via a call to |
d9c1ae64 | 166 | .BR inet_addr (3)) |
2f0af33b MK |
167 | for address type |
168 | .BR AF_INET . | |
fea681da | 169 | .PP |
60a90ecd MK |
170 | The |
171 | .BR sethostent () | |
172 | function specifies, if \fIstayopen\fP is true (1), | |
c13182ef MK |
173 | that a connected TCP socket should be used for the name server queries and |
174 | that the connection should remain open during successive queries. | |
175 | Otherwise, name server queries will use UDP datagrams. | |
fea681da | 176 | .PP |
60a90ecd MK |
177 | The |
178 | .BR endhostent () | |
179 | function ends the use of a TCP connection for name | |
fea681da MK |
180 | server queries. |
181 | .PP | |
60a90ecd MK |
182 | The (obsolete) |
183 | .BR herror () | |
184 | function prints the error message associated | |
ce2801d0 | 185 | with the current value of \fIh_errno\fP on \fIstderr\fP. |
fea681da | 186 | .PP |
60a90ecd MK |
187 | The (obsolete) |
188 | .BR hstrerror () | |
189 | function takes an error number | |
fea681da MK |
190 | (typically \fIh_errno\fP) and returns the corresponding message string. |
191 | .PP | |
60a90ecd MK |
192 | The domain name queries carried out by |
193 | .BR gethostbyname () | |
194 | and | |
195 | .BR gethostbyaddr () | |
196 | use a combination of any or all of the name server | |
fea681da MK |
197 | .BR named (8), |
198 | a broken out line from \fI/etc/hosts\fP, and the Network | |
199 | Information Service (NIS or YP), depending upon the contents of the | |
200 | \fIorder\fP line in | |
201 | .IR /etc/host.conf . | |
24268a72 MK |
202 | .\" (See |
203 | .\" .BR resolv+ (8)). | |
fea681da MK |
204 | The default action is to query |
205 | .BR named (8), | |
206 | followed by | |
207 | .IR /etc/hosts . | |
208 | .PP | |
209 | The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows: | |
210 | .sp | |
a08ea57c | 211 | .in +4n |
fea681da MK |
212 | .nf |
213 | .ne 7 | |
fea681da | 214 | struct hostent { |
b9f02710 MK |
215 | char *h_name; /* official name of host */ |
216 | char **h_aliases; /* alias list */ | |
217 | int h_addrtype; /* host address type */ | |
218 | int h_length; /* length of address */ | |
219 | char **h_addr_list; /* list of addresses */ | |
fea681da | 220 | } |
b9f02710 | 221 | #define h_addr h_addr_list[0] /* for backward compatibility */ |
fea681da | 222 | .fi |
a08ea57c | 223 | .in |
fea681da MK |
224 | .PP |
225 | The members of the \fIhostent\fP structure are: | |
226 | .TP | |
227 | .I h_name | |
228 | The official name of the host. | |
229 | .TP | |
230 | .I h_aliases | |
28d88c17 | 231 | An array of alternative names for the host, terminated by a NULL pointer. |
fea681da MK |
232 | .TP |
233 | .I h_addrtype | |
234 | The type of address; always | |
235 | .B AF_INET | |
236 | or | |
237 | .B AF_INET6 | |
238 | at present. | |
239 | .TP | |
240 | .I h_length | |
241 | The length of the address in bytes. | |
242 | .TP | |
243 | .I h_addr_list | |
28d88c17 MK |
244 | An array of pointers to network addresses for the host (in network byte |
245 | order), terminated by a NULL pointer. | |
fea681da MK |
246 | .TP |
247 | .I h_addr | |
248 | The first address in \fIh_addr_list\fP for backward compatibility. | |
249 | .SH "RETURN VALUE" | |
250 | The | |
251 | .BR gethostbyname () | |
252 | and | |
63aa9df0 | 253 | .BR gethostbyaddr () |
fea681da MK |
254 | functions return the |
255 | .I hostent | |
c13182ef MK |
256 | structure or a NULL pointer if an error occurs. |
257 | On error, the | |
fea681da MK |
258 | .I h_errno |
259 | variable holds an error number. | |
260 | When non-NULL, the return value may point at static data, see the notes below. | |
261 | .SH ERRORS | |
262 | The variable \fIh_errno\fP can have the following values: | |
263 | .TP | |
264 | .B HOST_NOT_FOUND | |
265 | The specified host is unknown. | |
266 | .TP | |
267 | .BR NO_ADDRESS " or " NO_DATA | |
268 | The requested name is valid but does not have an IP address. | |
269 | .TP | |
270 | .B NO_RECOVERY | |
271 | A non-recoverable name server error occurred. | |
272 | .TP | |
273 | .B TRY_AGAIN | |
c13182ef MK |
274 | A temporary error occurred on an authoritative name server. |
275 | Try again later. | |
fea681da MK |
276 | .SH FILES |
277 | .TP | |
278 | .I /etc/host.conf | |
279 | resolver configuration file | |
280 | .TP | |
281 | .I /etc/hosts | |
282 | host database file | |
24268a72 MK |
283 | .TP |
284 | .I /etc/nsswitch.conf | |
285 | name service switch configuration | |
fea681da | 286 | .SH "CONFORMING TO" |
12a1a9e7 MK |
287 | POSIX.1-2001 specifies |
288 | .BR gethostbyname (), | |
289 | .BR gethostbyaddr (), | |
290 | .BR sethostent (), | |
291 | .BR endhostent (), | |
292 | .BR gethostent (), | |
293 | and | |
294 | .IR h_errno . | |
381c50fd MK |
295 | POSIX.1-2008 removes the specifications of |
296 | .BR gethostbyname (), | |
297 | .BR gethostbyaddr (), | |
298 | and | |
299 | .IR h_errno . | |
8af1ba10 MK |
300 | .SH NOTES |
301 | The functions | |
302 | .BR gethostbyname () | |
303 | and | |
304 | .BR gethostbyaddr () | |
305 | may return pointers to static data, which may be overwritten by | |
306 | later calls. | |
307 | Copying the | |
308 | .I struct hostent | |
309 | does not suffice, since it contains pointers; a deep copy is required. | |
310 | .LP | |
988db661 | 311 | In the original BSD implementation the |
f9ee70bd MK |
312 | .I len |
313 | argument | |
988db661 | 314 | of |
f9ee70bd MK |
315 | .BR gethostbyname () |
316 | was an | |
317 | .IR int . | |
318 | The SUSv2 standard is buggy and declares the | |
8af1ba10 | 319 | .I len |
c4bb193f | 320 | argument of |
8af1ba10 MK |
321 | .BR gethostbyaddr () |
322 | to be of type | |
323 | .IR size_t . | |
324 | (That is wrong, because it has to be | |
325 | .IR int , | |
326 | and | |
327 | .I size_t | |
328 | is not. | |
329 | POSIX.1-2001 makes it | |
330 | .IR socklen_t , | |
331 | which is OK.) | |
f9ee70bd MK |
332 | See also |
333 | .BR accept (2). | |
8af1ba10 MK |
334 | .LP |
335 | The BSD prototype for | |
336 | .BR gethostbyaddr () | |
337 | uses | |
338 | .I const char * | |
339 | for the first argument. | |
340 | .LP | |
341 | POSIX.1-2001 marks | |
342 | .BR gethostbyaddr () | |
343 | and | |
344 | .BR gethostbyname () | |
345 | obsolescent. | |
b75101c3 | 346 | .\" FIXME . SUSv4 removes the specs for gethostbyname(), |
12a1a9e7 | 347 | .\" gethostbyaddr(), and h_errno. |
8af1ba10 MK |
348 | See |
349 | .BR getaddrinfo (3), | |
350 | .BR getnameinfo (3), | |
351 | .BR gai_strerror (3). | |
352 | .SS "System V/POSIX Extension" | |
fea681da MK |
353 | POSIX requires the |
354 | .BR gethostent () | |
355 | call, that should return the next entry in the host data base. | |
356 | When using DNS/BIND this does not make much sense, but it may | |
357 | be reasonable if the host data base is a file that can be read | |
c13182ef MK |
358 | line by line. |
359 | On many systems a routine of this name reads | |
fea681da MK |
360 | from the file |
361 | .IR /etc/hosts . | |
75b94dc3 | 362 | .\" e.g., Linux, FreeBSD, Unixware, HP-UX |
fea681da | 363 | It may be available only when the library was built without DNS support. |
75b94dc3 | 364 | .\" e.g., FreeBSD, AIX |
c13182ef MK |
365 | The glibc version will ignore ipv6 entries. |
366 | This function is not reentrant, | |
fea681da MK |
367 | and glibc adds a reentrant version |
368 | .BR gethostent_r (). | |
8af1ba10 | 369 | .SS "GNU Extensions" |
fea681da | 370 | Glibc2 also has a |
63aa9df0 | 371 | .BR gethostbyname2 () |
fea681da | 372 | that works like |
63aa9df0 | 373 | .BR gethostbyname (), |
fea681da MK |
374 | but permits to specify the address family to which the address must belong. |
375 | .LP | |
376 | Glibc2 also has reentrant versions | |
dd0fee67 MK |
377 | .BR gethostent_r (), |
378 | .BR gethostbyaddr_r (), | |
63aa9df0 | 379 | .BR gethostbyname_r () |
fea681da | 380 | and |
63aa9df0 | 381 | .BR gethostbyname2_r (). |
635e8d5a MK |
382 | The caller supplies a |
383 | .I hostent | |
384 | structure | |
dd0fee67 | 385 | .I ret |
635e8d5a | 386 | which will be filled in on success, and a temporary work buffer |
fea681da | 387 | .I buf |
dd0fee67 | 388 | of size |
fea681da | 389 | .IR buflen . |
dd0fee67 MK |
390 | After the call, |
391 | .I result | |
20523df7 MK |
392 | will point to the result on success. |
393 | In case of an error | |
dd0fee67 MK |
394 | or if no entry is found |
395 | .I result | |
635e8d5a | 396 | will be NULL. |
eba72288 | 397 | The functions return 0 on success and a non-zero error number on failure. |
dd0fee67 MK |
398 | In addition to the errors returned by the non-reentrant |
399 | versions of these functions, if | |
400 | .I buf | |
401 | is too small, the functions will return | |
402 | .BR ERANGE , | |
403 | and the call should be retried with a larger buffer. | |
404 | The global variable | |
fea681da | 405 | .I h_errno |
dd0fee67 | 406 | is not modified, but the address of a variable in which to store error numbers |
fea681da MK |
407 | is passed in |
408 | .IR h_errnop . | |
444aa1ce MK |
409 | .SH BUGS |
410 | .BR gethostbyname () | |
411 | does not recognize components of a dotted IPv4 address string | |
412 | that are expressed in hexadecimal. | |
413 | .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973 | |
fea681da MK |
414 | .SH "SEE ALSO" |
415 | .BR getaddrinfo (3), | |
652abd33 MK |
416 | .\" .BR getipnodebyaddr (3), |
417 | .\" .BR getipnodebyname (3), | |
fea681da | 418 | .BR getnameinfo (3), |
444aa1ce | 419 | .BR inet (3), |
fea681da MK |
420 | .BR inet_ntop (3), |
421 | .BR inet_pton (3), | |
422 | .BR resolver (3), | |
423 | .BR hosts (5), | |
24268a72 | 424 | .BR nsswitch.conf (5), |
fea681da | 425 | .BR hostname (7), |
24268a72 MK |
426 | .BR named (8) |
427 | .\" .BR resolv+ (8) |