xref: /freebsd/lib/libc/net/gethostbyname.3 (revision 076ad2f836d5f49dc1375f1677335a48fe0d4b82)
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. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     From: @(#)gethostbyname.3	8.4 (Berkeley) 5/25/95
29.\" $FreeBSD$
30.\"
31.Dd May 12, 2006
32.Dt GETHOSTBYNAME 3
33.Os
34.Sh NAME
35.Nm gethostbyname ,
36.Nm gethostbyname2 ,
37.Nm gethostbyaddr ,
38.Nm gethostent ,
39.Nm sethostent ,
40.Nm endhostent ,
41.Nm herror ,
42.Nm hstrerror
43.Nd get network host entry
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In netdb.h
48.Vt int h_errno ;
49.Ft struct hostent *
50.Fn gethostbyname "const char *name"
51.Ft struct hostent *
52.Fn gethostbyname2 "const char *name" "int af"
53.Ft struct hostent *
54.Fn gethostbyaddr "const void *addr" "socklen_t len" "int af"
55.Ft struct hostent *
56.Fn gethostent void
57.Ft void
58.Fn sethostent "int stayopen"
59.Ft void
60.Fn endhostent void
61.Ft void
62.Fn herror "const char *string"
63.Ft const char *
64.Fn hstrerror "int err"
65.Sh DESCRIPTION
66.Bf -symbolic
67The
68.Xr getaddrinfo 3
69and
70.Xr getnameinfo 3
71functions are preferred over the
72.Fn gethostbyname ,
73.Fn gethostbyname2 ,
74and
75.Fn gethostbyaddr
76functions.
77.Ef
78.Pp
79The
80.Fn gethostbyname ,
81.Fn gethostbyname2
82and
83.Fn gethostbyaddr
84functions
85each return a pointer to an object with the
86following structure describing an internet host
87referenced by name or by address, respectively.
88.Pp
89The
90.Fa name
91argument passed to
92.Fn gethostbyname
93or
94.Fn gethostbyname2
95should point to a
96.Dv NUL Ns -terminated
97hostname.
98The
99.Fa addr
100argument passed to
101.Fn gethostbyaddr
102should point to an address which is
103.Fa len
104bytes long,
105in binary form
106(i.e., not an IP address in human readable
107.Tn ASCII
108form).
109The
110.Fa af
111argument specifies the address family
112(e.g.\&
113.Dv AF_INET , AF_INET6 ,
114etc.) of this address.
115.Pp
116The structure returned contains either the information obtained from the name
117server,
118.Xr named 8 ,
119broken-out fields from a line in
120.Pa /etc/hosts ,
121or database entries supplied by the
122.Xr yp 8
123system.
124The order of the lookups is controlled by the
125.Sq hosts
126entry in
127.Xr nsswitch.conf 5 .
128.Bd -literal
129struct	hostent {
130	char	*h_name;	/* official name of host */
131	char	**h_aliases;	/* alias list */
132	int	h_addrtype;	/* host address type */
133	int	h_length;	/* length of address */
134	char	**h_addr_list;	/* list of addresses from name server */
135};
136#define	h_addr  h_addr_list[0]	/* address, for backward compatibility */
137.Ed
138.Pp
139The members of this structure are:
140.Bl -tag -width h_addr_list
141.It Va h_name
142Official name of the host.
143.It Va h_aliases
144A
145.Dv NULL Ns -terminated
146array of alternate names for the host.
147.It Va h_addrtype
148The type of address being returned; usually
149.Dv AF_INET .
150.It Va h_length
151The length, in bytes, of the address.
152.It Va h_addr_list
153A
154.Dv NULL Ns -terminated
155array of network addresses for the host.
156Host addresses are returned in network byte order.
157.It Va h_addr
158The first address in
159.Va h_addr_list ;
160this is for backward compatibility.
161.El
162.Pp
163When using the nameserver,
164.Fn gethostbyname
165and
166.Fn gethostbyname2
167will search for the named host in the current domain and its parents
168unless the name ends in a dot.
169If the name contains no dot, and if the environment variable
170.Dq Ev HOSTALIASES
171contains the name of an alias file, the alias file will first be searched
172for an alias matching the input name.
173See
174.Xr hostname 7
175for the domain search procedure and the alias file format.
176.Pp
177The
178.Fn gethostbyname2
179function is an evolution of
180.Fn gethostbyname
181which is intended to allow lookups in address families other than
182.Dv AF_INET ,
183for example
184.Dv AF_INET6 .
185.Pp
186The
187.Fn sethostent
188function
189may be used to request the use of a connected
190.Tn TCP
191socket for queries.
192If the
193.Fa stayopen
194flag is non-zero,
195this sets the option to send all queries to the name server using
196.Tn TCP
197and to retain the connection after each call to
198.Fn gethostbyname ,
199.Fn gethostbyname2
200or
201.Fn gethostbyaddr .
202Otherwise, queries are performed using
203.Tn UDP
204datagrams.
205.Pp
206The
207.Fn endhostent
208function
209closes the
210.Tn TCP
211connection.
212.Pp
213The
214.Fn herror
215function writes a message to the diagnostic output consisting of the
216string argument
217.Fa string ,
218the constant string
219.Qq Li ":\ " ,
220and a message corresponding to the value of
221.Va h_errno .
222.Pp
223The
224.Fn hstrerror
225function returns a string which is the message text corresponding to the
226value of the
227.Fa err
228argument.
229.Sh FILES
230.Bl -tag -width /etc/nsswitch.conf -compact
231.It Pa /etc/hosts
232.It Pa /etc/nsswitch.conf
233.It Pa /etc/resolv.conf
234.El
235.Sh EXAMPLES
236Print out the hostname associated with a specific IP address:
237.Bd -literal -offset indent
238const char *ipstr = "127.0.0.1";
239struct in_addr ip;
240struct hostent *hp;
241
242if (!inet_aton(ipstr, &ip))
243	errx(1, "can't parse IP address %s", ipstr);
244
245if ((hp = gethostbyaddr((const void *)&ip,
246    sizeof ip, AF_INET)) == NULL)
247	errx(1, "no name associated with %s", ipstr);
248
249printf("name associated with %s is %s\en", ipstr, hp->h_name);
250.Ed
251.Sh DIAGNOSTICS
252Error return status from
253.Fn gethostbyname ,
254.Fn gethostbyname2
255and
256.Fn gethostbyaddr
257is indicated by return of a
258.Dv NULL
259pointer.
260The integer
261.Va h_errno
262may then be checked to see whether this is a temporary failure
263or an invalid or unknown host.
264The routine
265.Fn herror
266can be used to print an error message describing the failure.
267If its argument
268.Fa string
269is
270.Pf non- Dv NULL ,
271it is printed, followed by a colon and a space.
272The error message is printed with a trailing newline.
273.Pp
274The variable
275.Va h_errno
276can have the following values:
277.Bl -tag -width HOST_NOT_FOUND
278.It Dv HOST_NOT_FOUND
279No such host is known.
280.It Dv TRY_AGAIN
281This is usually a temporary error
282and means that the local server did not receive
283a response from an authoritative server.
284A retry at some later time may succeed.
285.It Dv NO_RECOVERY
286Some unexpected server failure was encountered.
287This is a non-recoverable error.
288.It Dv NO_DATA
289The requested name is valid but does not have an IP address;
290this is not a temporary error.
291This means that the name is known to the name server but there is no address
292associated with this name.
293Another type of request to the name server using this domain name
294will result in an answer;
295for example, a mail-forwarder may be registered for this domain.
296.El
297.Sh SEE ALSO
298.Xr getaddrinfo 3 ,
299.Xr getnameinfo 3 ,
300.Xr inet_aton 3 ,
301.Xr resolver 3 ,
302.Xr hosts 5 ,
303.Xr hostname 7 ,
304.Xr named 8
305.Sh CAVEAT
306The
307.Fn gethostent
308function
309is defined, and
310.Fn sethostent
311and
312.Fn endhostent
313are redefined,
314when
315.Lb libc
316is built to use only the routines to lookup in
317.Pa /etc/hosts
318and not the name server.
319.Pp
320The
321.Fn gethostent
322function
323reads the next line of
324.Pa /etc/hosts ,
325opening the file if necessary.
326.Pp
327The
328.Fn sethostent
329function
330opens and/or rewinds the file
331.Pa /etc/hosts .
332If the
333.Fa stayopen
334argument is non-zero,
335the file will not be closed after each call to
336.Fn gethostbyname ,
337.Fn gethostbyname2
338or
339.Fn gethostbyaddr .
340.Pp
341The
342.Fn endhostent
343function
344closes the file.
345.Sh HISTORY
346The
347.Fn herror
348function appeared in
349.Bx 4.3 .
350The
351.Fn endhostent ,
352.Fn gethostbyaddr ,
353.Fn gethostbyname ,
354.Fn gethostent ,
355and
356.Fn sethostent
357functions appeared in
358.Bx 4.2 .
359The
360.Fn gethostbyname2
361function first appeared in
362.Tn BIND
363version 4.9.4.
364.Sh BUGS
365These functions use a thread-specific data storage;
366if the data is needed for future use, it should be
367copied before any subsequent calls overwrite it.
368.Pp
369Though these functions are thread-safe,
370still it is recommended to use the
371.Xr getaddrinfo 3
372family of functions, instead.
373.Pp
374Only the Internet
375address format is currently understood.
376