Commit | Line | Data |
---|---|---|
3b7c7bd7 A |
1 | .\" Copyright (c) 1983, 1987, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 | |
33 | .\" $FreeBSD: src/lib/libc/net/gethostbyname.3,v 1.12.2.6 2001/08/17 15:42:38 ru Exp $ | |
34 | .\" | |
35 | .Dd May 25, 1995 | |
36 | .Dt GETHOSTBYNAME 3 | |
37 | .Os | |
38 | .Sh NAME | |
39 | .Nm gethostbyname , | |
40 | .Nm gethostbyname2 , | |
41 | .Nm gethostbyaddr , | |
42 | .Nm gethostent , | |
43 | .Nm sethostent , | |
44 | .Nm endhostent , | |
45 | .Nm herror , | |
46 | .Nm hstrerror | |
47 | .Nd get network host entry | |
48 | .Sh LIBRARY | |
49 | .Lb libc | |
50 | .Sh SYNOPSIS | |
51 | .Fd #include <netdb.h> | |
52 | .Vt extern int h_errno ; | |
53 | .Ft struct hostent * | |
54 | .Fn gethostbyname "const char *name" | |
55 | .Ft struct hostent * | |
56 | .Fn gethostbyname2 "const char *name" "int af" | |
57 | .Ft struct hostent * | |
c29f2fcc | 58 | .Fn gethostbyaddr "const char *addr" "socklen_t len" "int type" |
3b7c7bd7 A |
59 | .Ft struct hostent * |
60 | .Fn gethostent void | |
61 | .Ft void | |
62 | .Fn sethostent "int stayopen" | |
63 | .Ft void | |
64 | .Fn endhostent void | |
65 | .Ft void | |
66 | .Fn herror "const char *string" | |
67 | .Ft const char * | |
68 | .Fn hstrerror "int err" | |
69 | .Sh DESCRIPTION | |
70 | The | |
71 | .Fn gethostbyname , | |
72 | .Fn gethostbyname2 | |
73 | and | |
74 | .Fn gethostbyaddr | |
75 | functions | |
76 | each return a pointer to an object with the | |
77 | following structure describing an internet host | |
78 | referenced by name or by address, respectively. | |
79 | This structure contains either the information obtained from the name server, | |
80 | .Xr named 8 , | |
81 | or broken-out fields from a line in | |
82 | .Pa /etc/hosts . | |
83 | If the local name server is not running these routines do a lookup in | |
84 | .Pa /etc/hosts . | |
85 | .Bd -literal | |
86 | struct hostent { | |
87 | char *h_name; /* official name of host */ | |
88 | char **h_aliases; /* alias list */ | |
89 | int h_addrtype; /* host address type */ | |
90 | int h_length; /* length of address */ | |
91 | char **h_addr_list; /* list of addresses from name server */ | |
92 | }; | |
93 | #define h_addr h_addr_list[0] /* address, for backward compatibility */ | |
94 | .Ed | |
95 | .Pp | |
96 | The members of this structure are: | |
97 | .Bl -tag -width h_addr_list | |
98 | .It Va h_name | |
99 | Official name of the host. | |
100 | .It Va h_aliases | |
101 | A | |
102 | .Dv NULL Ns -terminated | |
103 | array of alternate names for the host. | |
104 | .It Va h_addrtype | |
105 | The type of address being returned; usually | |
106 | .Dv AF_INET . | |
107 | .It Va h_length | |
108 | The length, in bytes, of the address. | |
109 | .It Va h_addr_list | |
110 | A | |
111 | .Dv NULL Ns -terminated | |
112 | array of network addresses for the host. | |
113 | Host addresses are returned in network byte order. | |
114 | .It Va h_addr | |
115 | The first address in | |
116 | .Va h_addr_list ; | |
117 | this is for backward compatibility. | |
118 | .El | |
119 | .Pp | |
120 | When using the nameserver, | |
121 | .Fn gethostbyname | |
122 | and | |
123 | .Fn gethostbyname2 | |
124 | will search for the named host in the current domain and its parents | |
125 | unless the name ends in a dot. | |
126 | If the name contains no dot, and if the environment variable | |
127 | .Dq Ev HOSTALIASES | |
128 | contains the name of an alias file, the alias file will first be searched | |
129 | for an alias matching the input name. | |
130 | See | |
131 | .Xr hostname 7 | |
132 | for the domain search procedure and the alias file format. | |
133 | .Pp | |
134 | The | |
135 | .Fn gethostbyname2 | |
136 | function is an evolution of | |
137 | .Fn gethostbyname | |
138 | which is intended to allow lookups in address families other than | |
139 | .Dv AF_INET , | |
140 | for example | |
141 | .Dv AF_INET6 . | |
ccd4a120 | 142 | Both of these address families are supported in the Mac OS X implemention. |
3b7c7bd7 A |
143 | .Pp |
144 | The | |
145 | .Fn sethostent | |
146 | function | |
147 | may be used to request the use of a connected | |
148 | .Tn TCP | |
149 | socket for queries. | |
150 | If the | |
151 | .Fa stayopen | |
152 | flag is non-zero, | |
153 | this sets the option to send all queries to the name server using | |
154 | .Tn TCP | |
155 | and to retain the connection after each call to | |
156 | .Fn gethostbyname , | |
157 | .Fn gethostbyname2 | |
158 | or | |
159 | .Fn gethostbyaddr . | |
160 | Otherwise, queries are performed using | |
161 | .Tn UDP | |
162 | datagrams. | |
163 | .Pp | |
164 | The | |
165 | .Fn endhostent | |
166 | function | |
167 | closes the | |
168 | .Tn TCP | |
169 | connection. | |
170 | .Pp | |
171 | The | |
172 | .Fn herror | |
173 | function writes a message to the diagnostic output consisting of the | |
174 | string parameter | |
175 | .Fa s , | |
176 | the constant string | |
177 | .Qq Li ":\ " , | |
178 | and a message corresponding to the value of | |
179 | .Va h_errno . | |
180 | .Pp | |
181 | The | |
182 | .Fn hstrerror | |
183 | function returns a string which is the message text corresponding to the | |
184 | value of the | |
185 | .Fa err | |
186 | parameter. | |
187 | .Sh FILES | |
188 | .Bl -tag -width /etc/resolv.conf -compact | |
189 | .It Pa /etc/hosts | |
190 | .It Pa /etc/host.conf | |
191 | .It Pa /etc/resolv.conf | |
192 | .El | |
193 | .Sh DIAGNOSTICS | |
194 | Error return status from | |
195 | .Fn gethostbyname , | |
196 | .Fn gethostbyname2 | |
197 | and | |
198 | .Fn gethostbyaddr | |
199 | is indicated by return of a | |
200 | .Dv NULL | |
201 | pointer. | |
202 | The external integer | |
203 | .Va h_errno | |
204 | may then be checked to see whether this is a temporary failure | |
205 | or an invalid or unknown host. | |
206 | The routine | |
207 | .Fn herror | |
208 | can be used to print an error message describing the failure. | |
209 | If its argument | |
210 | .Fa string | |
211 | is | |
212 | .Pf non- Dv NULL , | |
213 | it is printed, followed by a colon and a space. | |
214 | The error message is printed with a trailing newline. | |
215 | .Pp | |
216 | The variable | |
217 | .Va h_errno | |
218 | can have the following values: | |
219 | .Bl -tag -width HOST_NOT_FOUND | |
220 | .It Dv HOST_NOT_FOUND | |
221 | No such host is known. | |
222 | .It Dv TRY_AGAIN | |
223 | This is usually a temporary error | |
224 | and means that the local server did not receive | |
225 | a response from an authoritative server. | |
226 | A retry at some later time may succeed. | |
227 | .It Dv NO_RECOVERY | |
228 | Some unexpected server failure was encountered. | |
229 | This is a non-recoverable error. | |
230 | .It Dv NO_DATA | |
231 | The requested name is valid but does not have an IP address; | |
232 | this is not a temporary error. | |
233 | This means that the name is known to the name server but there is no address | |
234 | associated with this name. | |
235 | Another type of request to the name server using this domain name | |
236 | will result in an answer; | |
237 | for example, a mail-forwarder may be registered for this domain. | |
238 | .El | |
239 | .Sh SEE ALSO | |
240 | .Xr getaddrinfo 3 , | |
241 | .Xr resolver 3 , | |
242 | .Xr hosts 5 , | |
243 | .Xr hostname 7 , | |
244 | .Xr named 8 | |
245 | .Sh CAVEAT | |
246 | The | |
247 | .Fn gethostent | |
248 | function | |
249 | is defined, and | |
250 | .Fn sethostent | |
251 | and | |
252 | .Fn endhostent | |
253 | are redefined, | |
ccd4a120 | 254 | when libc is built to use only the routines to lookup in |
3b7c7bd7 A |
255 | .Pa /etc/hosts |
256 | and not the name server. | |
257 | .Pp | |
258 | The | |
259 | .Fn gethostent | |
260 | function | |
261 | reads the next line of | |
262 | .Pa /etc/hosts , | |
263 | opening the file if necessary. | |
264 | .Pp | |
265 | The | |
266 | .Fn sethostent | |
267 | function | |
268 | opens and/or rewinds the file | |
269 | .Pa /etc/hosts . | |
270 | If the | |
271 | .Fa stayopen | |
272 | argument is non-zero, | |
273 | the file will not be closed after each call to | |
274 | .Fn gethostbyname , | |
275 | .Fn gethostbyname2 | |
276 | or | |
277 | .Fn gethostbyaddr . | |
278 | .Pp | |
279 | The | |
280 | .Fn endhostent | |
281 | function | |
282 | closes the file. | |
283 | .Sh HISTORY | |
284 | The | |
285 | .Fn herror | |
286 | function appeared in | |
287 | .Bx 4.3 . | |
288 | The | |
289 | .Fn endhostent , | |
290 | .Fn gethostbyaddr , | |
291 | .Fn gethostbyname , | |
292 | .Fn gethostent , | |
293 | and | |
294 | .Fn sethostent | |
295 | functions appeared in | |
296 | .Bx 4.2 . | |
297 | The | |
298 | .Fn gethostbyname2 | |
299 | function first appeared in | |
300 | .Tn BIND | |
301 | version 4.9.4. | |
302 | .Sh BUGS | |
303 | These functions use static data storage; | |
304 | if the data is needed for future use, it should be | |
305 | copied before any subsequent calls overwrite it. | |
306 | Only the Internet | |
307 | address format is currently understood. |