Libinfo-222.4.12.tar.gz
[apple/libinfo.git] / gen.subproj / gethostbyname.3
CommitLineData
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
70The
71.Fn gethostbyname ,
72.Fn gethostbyname2
73and
74.Fn gethostbyaddr
75functions
76each return a pointer to an object with the
77following structure describing an internet host
78referenced by name or by address, respectively.
79This structure contains either the information obtained from the name server,
80.Xr named 8 ,
81or broken-out fields from a line in
82.Pa /etc/hosts .
83If the local name server is not running these routines do a lookup in
84.Pa /etc/hosts .
85.Bd -literal
86struct 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
96The members of this structure are:
97.Bl -tag -width h_addr_list
98.It Va h_name
99Official name of the host.
100.It Va h_aliases
101A
102.Dv NULL Ns -terminated
103array of alternate names for the host.
104.It Va h_addrtype
105The type of address being returned; usually
106.Dv AF_INET .
107.It Va h_length
108The length, in bytes, of the address.
109.It Va h_addr_list
110A
111.Dv NULL Ns -terminated
112array of network addresses for the host.
113Host addresses are returned in network byte order.
114.It Va h_addr
115The first address in
116.Va h_addr_list ;
117this is for backward compatibility.
118.El
119.Pp
120When using the nameserver,
121.Fn gethostbyname
122and
123.Fn gethostbyname2
124will search for the named host in the current domain and its parents
125unless the name ends in a dot.
126If the name contains no dot, and if the environment variable
127.Dq Ev HOSTALIASES
128contains the name of an alias file, the alias file will first be searched
129for an alias matching the input name.
130See
131.Xr hostname 7
132for the domain search procedure and the alias file format.
133.Pp
134The
135.Fn gethostbyname2
136function is an evolution of
137.Fn gethostbyname
138which is intended to allow lookups in address families other than
139.Dv AF_INET ,
140for example
141.Dv AF_INET6 .
ccd4a120 142Both of these address families are supported in the Mac OS X implemention.
3b7c7bd7
A
143.Pp
144The
145.Fn sethostent
146function
147may be used to request the use of a connected
148.Tn TCP
149socket for queries.
150If the
151.Fa stayopen
152flag is non-zero,
153this sets the option to send all queries to the name server using
154.Tn TCP
155and to retain the connection after each call to
156.Fn gethostbyname ,
157.Fn gethostbyname2
158or
159.Fn gethostbyaddr .
160Otherwise, queries are performed using
161.Tn UDP
162datagrams.
163.Pp
164The
165.Fn endhostent
166function
167closes the
168.Tn TCP
169connection.
170.Pp
171The
172.Fn herror
173function writes a message to the diagnostic output consisting of the
174string parameter
175.Fa s ,
176the constant string
177.Qq Li ":\ " ,
178and a message corresponding to the value of
179.Va h_errno .
180.Pp
181The
182.Fn hstrerror
183function returns a string which is the message text corresponding to the
184value of the
185.Fa err
186parameter.
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
194Error return status from
195.Fn gethostbyname ,
196.Fn gethostbyname2
197and
198.Fn gethostbyaddr
199is indicated by return of a
200.Dv NULL
201pointer.
202The external integer
203.Va h_errno
204may then be checked to see whether this is a temporary failure
205or an invalid or unknown host.
206The routine
207.Fn herror
208can be used to print an error message describing the failure.
209If its argument
210.Fa string
211is
212.Pf non- Dv NULL ,
213it is printed, followed by a colon and a space.
214The error message is printed with a trailing newline.
215.Pp
216The variable
217.Va h_errno
218can have the following values:
219.Bl -tag -width HOST_NOT_FOUND
220.It Dv HOST_NOT_FOUND
221No such host is known.
222.It Dv TRY_AGAIN
223This is usually a temporary error
224and means that the local server did not receive
225a response from an authoritative server.
226A retry at some later time may succeed.
227.It Dv NO_RECOVERY
228Some unexpected server failure was encountered.
229This is a non-recoverable error.
230.It Dv NO_DATA
231The requested name is valid but does not have an IP address;
232this is not a temporary error.
233This means that the name is known to the name server but there is no address
234associated with this name.
235Another type of request to the name server using this domain name
236will result in an answer;
237for 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
246The
247.Fn gethostent
248function
249is defined, and
250.Fn sethostent
251and
252.Fn endhostent
253are redefined,
ccd4a120 254when libc is built to use only the routines to lookup in
3b7c7bd7
A
255.Pa /etc/hosts
256and not the name server.
257.Pp
258The
259.Fn gethostent
260function
261reads the next line of
262.Pa /etc/hosts ,
263opening the file if necessary.
264.Pp
265The
266.Fn sethostent
267function
268opens and/or rewinds the file
269.Pa /etc/hosts .
270If the
271.Fa stayopen
272argument is non-zero,
273the file will not be closed after each call to
274.Fn gethostbyname ,
275.Fn gethostbyname2
276or
277.Fn gethostbyaddr .
278.Pp
279The
280.Fn endhostent
281function
282closes the file.
283.Sh HISTORY
284The
285.Fn herror
286function appeared in
287.Bx 4.3 .
288The
289.Fn endhostent ,
290.Fn gethostbyaddr ,
291.Fn gethostbyname ,
292.Fn gethostent ,
293and
294.Fn sethostent
295functions appeared in
296.Bx 4.2 .
297The
298.Fn gethostbyname2
299function first appeared in
300.Tn BIND
301version 4.9.4.
302.Sh BUGS
303These functions use static data storage;
304if the data is needed for future use, it should be
305copied before any subsequent calls overwrite it.
306Only the Internet
307address format is currently understood.