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