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