xref: /freebsd/lib/libc/net/gethostbyname.3 (revision 6137b5f7b8c183ee8806d79b3f1d8e5e3ddb3df3)
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.Dd June 27, 2022
29.Dt GETHOSTBYNAME 3
30.Os
31.Sh NAME
32.Nm gethostbyname ,
33.Nm gethostbyname2 ,
34.Nm gethostbyaddr ,
35.Nm gethostent ,
36.Nm sethostent ,
37.Nm endhostent ,
38.Nm herror ,
39.Nm hstrerror ,
40.Nm gethostbyname_r ,
41.Nm gethostbyname2_r ,
42.Nm gethostbyaddr_r
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.Ft int
66.Fn gethostbyname_r "const char *name" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
67.Ft int
68.Fn gethostbyname2_r "const char *name" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
69.Ft int
70.Fn gethostbyaddr_r "const void *addr" "socklen_t len" "int af" "struct hostent *hp" "char *buf" "size_t buflen" "struct hostent **result" "int *h_errno"p
71.Sh DESCRIPTION
72.Bf -symbolic
73The
74.Xr getaddrinfo 3
75and
76.Xr getnameinfo 3
77functions are preferred over the
78.Fn gethostbyname ,
79.Fn gethostbyname2 ,
80and
81.Fn gethostbyaddr
82functions.
83.Ef
84.Pp
85The
86.Fn gethostbyname ,
87.Fn gethostbyname2
88and
89.Fn gethostbyaddr
90functions
91each return a pointer to an object with the
92following structure describing an internet host
93referenced by name or by address, respectively.
94.Pp
95The
96.Fa name
97argument passed to
98.Fn gethostbyname
99or
100.Fn gethostbyname2
101should point to a
102.Dv NUL Ns -terminated
103hostname.
104The
105.Fa addr
106argument passed to
107.Fn gethostbyaddr
108should point to an address which is
109.Fa len
110bytes long,
111in binary form
112(i.e., not an IP address in human readable
113.Tn ASCII
114form).
115The
116.Fa af
117argument specifies the address family
118(e.g.\&
119.Dv AF_INET , AF_INET6 ,
120etc.) of this address.
121.Pp
122The structure returned contains either the information obtained from the name
123server, broken-out fields from a line in
124.Pa /etc/hosts ,
125or database entries supplied by the
126.Xr yp 8
127system.
128The order of the lookups is controlled by the
129.Sq hosts
130entry in
131.Xr nsswitch.conf 5 .
132.Bd -literal
133struct	hostent {
134	char	*h_name;	/* official name of host */
135	char	**h_aliases;	/* alias list */
136	int	h_addrtype;	/* host address type */
137	int	h_length;	/* length of address */
138	char	**h_addr_list;	/* list of addresses from name server */
139};
140#define	h_addr  h_addr_list[0]	/* address, for backward compatibility */
141.Ed
142.Pp
143The members of this structure are:
144.Bl -tag -width h_addr_list
145.It Va h_name
146Official name of the host.
147.It Va h_aliases
148A
149.Dv NULL Ns -terminated
150array of alternate names for the host.
151.It Va h_addrtype
152The type of address being returned; usually
153.Dv AF_INET .
154.It Va h_length
155The length, in bytes, of the address.
156.It Va h_addr_list
157A
158.Dv NULL Ns -terminated
159array of network addresses for the host.
160Host addresses are returned in network byte order.
161.It Va h_addr
162The first address in
163.Va h_addr_list ;
164this is for backward compatibility.
165.El
166.Pp
167When using the nameserver,
168.Fn gethostbyname
169and
170.Fn gethostbyname2
171will search for the named host in the current domain and its parents
172unless the name ends in a dot.
173If the name contains no dot, and if the environment variable
174.Dq Ev HOSTALIASES
175contains the name of an alias file, the alias file will first be searched
176for an alias matching the input name.
177See
178.Xr hostname 7
179for the domain search procedure and the alias file format.
180.Pp
181The
182.Fn gethostbyname2
183function is an evolution of
184.Fn gethostbyname
185which is intended to allow lookups in address families other than
186.Dv AF_INET ,
187for example
188.Dv AF_INET6 .
189.Pp
190The
191.Fn sethostent
192function
193may be used to request the use of a connected
194.Tn TCP
195socket for queries.
196Queries will by default use
197.Tn UDP
198datagrams.
199If the
200.Fa stayopen
201flag is non-zero, a
202.Tn TCP
203connection to the name server will be used.
204It will remain open after calls to
205.Fn gethostbyname ,
206.Fn gethostbyname2
207or
208.Fn gethostbyaddr
209have completed.
210.Pp
211The
212.Fn endhostent
213function
214closes the
215.Tn TCP
216connection.
217.Pp
218The
219.Fn herror
220function writes a message to the diagnostic output consisting of the
221string argument
222.Fa string ,
223the constant string
224.Qq Li ":\ " ,
225and a message corresponding to the value of
226.Va h_errno .
227.Pp
228The
229.Fn hstrerror
230function returns a string which is the message text corresponding to the
231value of the
232.Fa err
233argument.
234.Pp
235Functions with the
236.Em _r
237suffix provide reentrant versions of their respective counterparts.
238The caller must supply five additional parameters: a
239.Vt struct hostent
240variable to be filled on success, a
241.Va buffer
242of
243.Va buflen
244bytes in size, a
245.Vt struct hostent
246.Va result
247variable that will point to the result on success or be set to
248.Dv NULL
249on failure or if the name is not found.
250The
251.Va h_errnop
252variable will be filled with the error code if any.
253All these functions return 0 on success.
254.Sh FILES
255.Bl -tag -width /etc/nsswitch.conf -compact
256.It Pa /etc/hosts
257.It Pa /etc/nsswitch.conf
258.It Pa /etc/resolv.conf
259.El
260.Sh EXAMPLES
261Print out the hostname associated with a specific IP address:
262.Bd -literal -offset indent
263const char *ipstr = "127.0.0.1";
264struct in_addr ip;
265struct hostent *hp;
266
267if (!inet_aton(ipstr, &ip))
268	errx(1, "can't parse IP address %s", ipstr);
269
270if ((hp = gethostbyaddr((const void *)&ip,
271    sizeof ip, AF_INET)) == NULL)
272	errx(1, "no name associated with %s", ipstr);
273
274printf("name associated with %s is %s\en", ipstr, hp->h_name);
275.Ed
276.Sh DIAGNOSTICS
277Error return status from
278.Fn gethostbyname ,
279.Fn gethostbyname2
280and
281.Fn gethostbyaddr
282is indicated by return of a
283.Dv NULL
284pointer.
285The integer
286.Va h_errno
287may then be checked to see whether this is a temporary failure
288or an invalid or unknown host.
289The routine
290.Fn herror
291can be used to print an error message describing the failure.
292If its argument
293.Fa string
294is
295.Pf non- Dv NULL ,
296it is printed, followed by a colon and a space.
297The error message is printed with a trailing newline.
298.Pp
299The variable
300.Va h_errno
301can have the following values:
302.Bl -tag -width HOST_NOT_FOUND
303.It Dv HOST_NOT_FOUND
304No such host is known.
305.It Dv TRY_AGAIN
306This is usually a temporary error
307and means that the local server did not receive
308a response from an authoritative server.
309A retry at some later time may succeed.
310.It Dv NO_RECOVERY
311Some unexpected server failure was encountered.
312This is a non-recoverable error.
313.It Dv NO_DATA
314The requested name is valid but does not have an IP address;
315this is not a temporary error.
316This means that the name is known to the name server but there is no address
317associated with this name.
318Another type of request to the name server using this domain name
319will result in an answer;
320for example, a mail-forwarder may be registered for this domain.
321.El
322.Sh SEE ALSO
323.Xr getaddrinfo 3 ,
324.Xr getnameinfo 3 ,
325.Xr inet_aton 3 ,
326.Xr resolver 3 ,
327.Xr hosts 5 ,
328.Xr hostname 7
329.Sh HISTORY
330The
331.Fn herror
332function appeared in
333.Bx 4.3 .
334The
335.Fn endhostent ,
336.Fn gethostbyaddr ,
337.Fn gethostbyname ,
338.Fn gethostent ,
339and
340.Fn sethostent
341functions appeared in
342.Bx 4.2 .
343The
344.Fn gethostbyname2
345function first appeared in
346.Tn BIND
347version 4.9.4.
348The
349.Fn gethostbyname_r
350function first appeared in
351.Fx 6.2 .
352.Sh CAVEATS
353The
354.Fn gethostent
355function
356is defined, and
357.Fn sethostent
358and
359.Fn endhostent
360are redefined,
361when
362.Lb libc
363is built to use only the routines to lookup in
364.Pa /etc/hosts
365and not the name server.
366.Pp
367The
368.Fn gethostent
369function
370reads the next line of
371.Pa /etc/hosts ,
372opening the file if necessary.
373.Pp
374The
375.Fn sethostent
376function
377opens and/or rewinds the file
378.Pa /etc/hosts .
379If the
380.Fa stayopen
381argument is non-zero,
382the file will not be closed after each call to
383.Fn gethostbyname ,
384.Fn gethostbyname2
385or
386.Fn gethostbyaddr .
387.Pp
388The
389.Fn endhostent
390function
391closes the file.
392.Sh BUGS
393These functions use a thread-specific data storage;
394if the data is needed for future use, it should be
395copied before any subsequent calls overwrite it.
396.Pp
397Though these functions are thread-safe,
398still it is recommended to use the
399.Xr getaddrinfo 3
400family of functions, instead.
401.Pp
402Only the Internet
403address format is currently understood.
404