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