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