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 | .\" $Id$ |
---|
34 | .\" |
---|
35 | .Dd May 25, 1995 |
---|
36 | .Dt GETHOSTBYNAME 3 |
---|
37 | .Os BSD 4.2 |
---|
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 SYNOPSIS |
---|
49 | .Fd #include <netdb.h> |
---|
50 | .Vt extern int h_errno; |
---|
51 | .Ft struct hostent * |
---|
52 | .Fn gethostbyname "const char *name" |
---|
53 | .Ft struct hostent * |
---|
54 | .Fn gethostbyname2 "const char *name" "int af" |
---|
55 | .Ft struct hostent * |
---|
56 | .Fn gethostbyaddr "const char *addr" "int len" "int type" |
---|
57 | .Ft struct hostent * |
---|
58 | .Fn gethostent void |
---|
59 | .Ft void |
---|
60 | .Fn sethostent "int stayopen" |
---|
61 | .Ft void |
---|
62 | .Fn endhostent void |
---|
63 | .Ft void |
---|
64 | .Fn herror "const char *string" |
---|
65 | .Ft const char * |
---|
66 | .Fn hstrerror "int err" |
---|
67 | .Sh DESCRIPTION |
---|
68 | The |
---|
69 | .Fn gethostbyname , |
---|
70 | .Fn gethostbyname2 |
---|
71 | and |
---|
72 | .Fn gethostbyaddr |
---|
73 | functions |
---|
74 | each return a pointer to an object with the |
---|
75 | following structure describing an internet host |
---|
76 | referenced by name or by address, respectively. |
---|
77 | This structure contains either the information obtained from the name server, |
---|
78 | .Xr named 8 , |
---|
79 | or broken-out fields from a line in |
---|
80 | .Pa /etc/hosts . |
---|
81 | If the local name server is not running these routines do a lookup in |
---|
82 | .Pa /etc/hosts . |
---|
83 | .Bd -literal |
---|
84 | struct hostent { |
---|
85 | char *h_name; /* official name of host */ |
---|
86 | char **h_aliases; /* alias list */ |
---|
87 | int h_addrtype; /* host address type */ |
---|
88 | int h_length; /* length of address */ |
---|
89 | char **h_addr_list; /* list of addresses from name server */ |
---|
90 | }; |
---|
91 | #define h_addr h_addr_list[0] /* address, for backward compatibility */ |
---|
92 | .Ed |
---|
93 | .Pp |
---|
94 | The members of this structure are: |
---|
95 | .Bl -tag -width h_addr_list |
---|
96 | .It Fa h_name |
---|
97 | Official name of the host. |
---|
98 | .It Fa h_aliases |
---|
99 | A NULL-terminated array of alternate names for the host. |
---|
100 | .It Fa h_addrtype |
---|
101 | The type of address being returned; usually |
---|
102 | .Dv AF_INET . |
---|
103 | .It Fa h_length |
---|
104 | The length, in bytes, of the address. |
---|
105 | .It Fa h_addr_list |
---|
106 | A NULL-terminated array of network addresses for the host. |
---|
107 | Host addresses are returned in network byte order. |
---|
108 | .It Fa h_addr |
---|
109 | The first address in |
---|
110 | .Fa h_addr_list ; |
---|
111 | this is for backward compatibility. |
---|
112 | .El |
---|
113 | .Pp |
---|
114 | When using the nameserver, |
---|
115 | .Fn gethostbyname |
---|
116 | and |
---|
117 | .Fn gethostbyname |
---|
118 | will search for the named host in the current domain and its parents |
---|
119 | unless the name ends in a dot. |
---|
120 | If the name contains no dot, and if the environment variable |
---|
121 | .Dq Ev HOSTALIASES |
---|
122 | contains the name of an alias file, the alias file will first be searched |
---|
123 | for an alias matching the input name. |
---|
124 | See |
---|
125 | .Xr hostname 7 |
---|
126 | for the domain search procedure and the alias file format. |
---|
127 | .Pp |
---|
128 | The |
---|
129 | .Fn gethostbyname2 |
---|
130 | function is an evolution of |
---|
131 | .Fn gethostbyname |
---|
132 | which is intended to allow lookups in address families other than |
---|
133 | .Dv AF_INET , |
---|
134 | for example |
---|
135 | .Dv AF_INET6 . |
---|
136 | Currently the |
---|
137 | .Fa af |
---|
138 | argument must be specified as |
---|
139 | .Dv AF_INET |
---|
140 | else the function will return |
---|
141 | .Dv NULL |
---|
142 | after having set |
---|
143 | .Va h_errno |
---|
144 | to |
---|
145 | .Dv NETDB_INTERNAL |
---|
146 | .Pp |
---|
147 | The |
---|
148 | .Fn sethostent |
---|
149 | function |
---|
150 | may be used to request the use of a connected |
---|
151 | .Tn TCP |
---|
152 | socket for queries. |
---|
153 | If the |
---|
154 | .Fa stayopen |
---|
155 | flag is non-zero, |
---|
156 | this sets the option to send all queries to the name server using |
---|
157 | .Tn TCP |
---|
158 | and to retain the connection after each call to |
---|
159 | .Fn gethostbyname , |
---|
160 | .Fn gethostbyname2 |
---|
161 | or |
---|
162 | .Fn gethostbyaddr . |
---|
163 | Otherwise, queries are performed using |
---|
164 | .Tn UDP |
---|
165 | datagrams. |
---|
166 | .Pp |
---|
167 | The |
---|
168 | .Fn endhostent |
---|
169 | function |
---|
170 | closes the |
---|
171 | .Tn TCP |
---|
172 | connection. |
---|
173 | .Pp |
---|
174 | The |
---|
175 | .Fn herror |
---|
176 | function writes a message to the diagnostic output consisting of the |
---|
177 | string parameter |
---|
178 | .Fa s , |
---|
179 | the constant string ": ", and a message corresponding to the value of |
---|
180 | .Va h_errno . |
---|
181 | .Pp |
---|
182 | The |
---|
183 | .Fn hstrerror |
---|
184 | function returns a string which is the message text corresponding to the |
---|
185 | value of the |
---|
186 | .Fa err |
---|
187 | parameter. |
---|
188 | .Sh FILES |
---|
189 | .Bl -tag -width /etc/resolv.conf -compact |
---|
190 | .It Pa /etc/hosts |
---|
191 | .It Pa /etc/host.conf |
---|
192 | .It Pa /etc/resolv.conf |
---|
193 | .El |
---|
194 | .Sh DIAGNOSTICS |
---|
195 | Error return status from |
---|
196 | .Fn gethostbyname , |
---|
197 | .Fn gethostbyname2 |
---|
198 | and |
---|
199 | .Fn gethostbyaddr |
---|
200 | is indicated by return of a null pointer. |
---|
201 | The external integer |
---|
202 | .Va h_errno |
---|
203 | may then be checked to see whether this is a temporary failure |
---|
204 | or an invalid or unknown host. |
---|
205 | The routine |
---|
206 | .Fn herror |
---|
207 | can be used to print an error message describing the failure. |
---|
208 | If its argument |
---|
209 | .Fa string |
---|
210 | is |
---|
211 | .Pf non Dv -NULL , |
---|
212 | it is printed, followed by a colon and a space. |
---|
213 | The error message is printed with a trailing newline. |
---|
214 | .Pp |
---|
215 | The variable |
---|
216 | .Va h_errno |
---|
217 | can have the following values: |
---|
218 | .Bl -tag -width HOST_NOT_FOUND |
---|
219 | .It Dv HOST_NOT_FOUND |
---|
220 | No such host is known. |
---|
221 | .It Dv TRY_AGAIN |
---|
222 | This is usually a temporary error |
---|
223 | and means that the local server did not receive |
---|
224 | a response from an authoritative server. |
---|
225 | A retry at some later time may succeed. |
---|
226 | .It Dv NO_RECOVERY |
---|
227 | Some unexpected server failure was encountered. |
---|
228 | This is a non-recoverable error. |
---|
229 | .It Dv NO_DATA |
---|
230 | The requested name is valid but does not have an IP address; |
---|
231 | this is not a temporary error. |
---|
232 | This means that the name is known to the name server but there is no address |
---|
233 | associated with this name. |
---|
234 | Another type of request to the name server using this domain name |
---|
235 | will result in an answer; |
---|
236 | for example, a mail-forwarder may be registered for this domain. |
---|
237 | .El |
---|
238 | .Sh SEE ALSO |
---|
239 | .Xr resolver 3 , |
---|
240 | .Xr hosts 5 , |
---|
241 | .Xr hostname 7 , |
---|
242 | .Xr named 8 |
---|
243 | .Sh CAVEAT |
---|
244 | The |
---|
245 | .Fn gethostent |
---|
246 | function |
---|
247 | is defined, and |
---|
248 | .Fn sethostent |
---|
249 | and |
---|
250 | .Fn endhostent |
---|
251 | are redefined, |
---|
252 | when |
---|
253 | .Xr libc 3 |
---|
254 | is built to use only the routines to lookup in |
---|
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 bind-4.9.4. |
---|
300 | .Sh BUGS |
---|
301 | These functions use static data storage; |
---|
302 | if the data is needed for future use, it should be |
---|
303 | copied before any subsequent calls overwrite it. |
---|
304 | Only the Internet |
---|
305 | address format is currently understood. |
---|