1.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
2.\" Copyright (c) 1996,1999 by Internet Software Consortium
3.\"
4.\" Permission to use, copy, modify, and distribute this software for any
5.\" purpose with or without fee is hereby granted, provided that the above
6.\" copyright notice and this permission notice appear in all copies.
7.\"
8.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
14.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15.\"
16.\" Copyright (c) 1983, 1987 The Regents of the University of California.
17.\" All rights reserved.
18.\"
19.\" Redistribution and use in source and binary forms are permitted provided
20.\" that: (1) source distributions retain this entire copyright notice and
21.\" comment, and (2) distributions including binaries display the following
22.\" acknowledgement:  ``This product includes software developed by the
23.\" University of California, Berkeley and its contributors'' in the
24.\" documentation or other materials provided with the distribution and in
25.\" all advertising materials mentioning features or use of this software.
26.\" Neither the name of the University nor the names of its contributors may
27.\" be used to endorse or promote products derived from this software without
28.\" specific prior written permission.
29.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
30.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
31.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
32.\"
33.Dd September 17, 1999
34.Dt GETIPNODEBYNAME 3
35.Os BSD 4
36.Sh NAME
37.Nm getipnodebyname ,
38.Nm getipnodebyaddr
39.Nd get network host entry
40.br
41.Nm freehostent
42.Nd free network host entry
43.Sh SYNOPSIS
44.Fd #include <netdb.h>
45.Pp
46.Ft struct hostent *
47.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error"
48.Ft struct hostent *
49.Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error"
50.Ft void
51.Fn freehostent "struct hostent *he"
52.Sh DESCRIPTION
53.Fn Getipnodebyname ,
54and
55.Fn getipnodebyaddr
56each return a pointer to a
57.Ft hostent
58structure (see below) describing an internet host
59referenced by name or by address, as the function names indicate.
60This structure contains either the information obtained from the name server,
61or broken-out fields from a line in
62.Pa /etc/hosts .
63If the local name server is not running, these routines do a lookup in
64.Pa /etc/hosts .
65.Bd -literal -offset indent
66struct	hostent {
67	char	*h_name;	/* official name of host */
68	char	**h_aliases;	/* alias list */
69	int	h_addrtype;	/* host address type */
70	int	h_length;	/* length of address */
71	char	**h_addr_list;	/* list of addresses from name server */
72};
73
74#define	h_addr  h_addr_list[0]	/* address, for backward compatibility */
75.Ed
76.Pp
77The members of this structure are:
78.Bl -tag -width "h_addr_list"
79.It h_name
80Official name of the host.
81.It h_aliases
82A zero-terminated array of alternate names for the host.
83.It h_addrtype
84The type of address being returned.
85.It h_length
86The length, in bytes, of the address.
87.It h_addr_list
88A zero-terminated array of network addresses for the host.
89Host addresses are returned in network byte order.
90.It h_addr
91The first address in
92.Li h_addr_list ;
93this is for backward compatibility.
94.El
95.Pp
96This structure should be freed after use by calling
97.Fn freehostent .
98.Pp
99When using the nameserver,
100.Fn getiphostbyaddr
101will search for the named host in each parent domain given in the
102.Dq Li search
103directive of
104.Xr resolv.conf 5
105unless the name contains a dot
106.Pq Dq \&. .
107If the name contains no dot, and if the environment variable
108.Ev HOSTALIASES
109contains the name of an alias file, the alias file will first be searched
110for an alias matching the input name.
111See
112.Xr hostname 7
113for the domain search procedure and the alias file format.
114.Pp
115.Fn Getiphostbyaddr
116can be told to look for IPv4 addresses, IPv6 addresses or both IPv4 and IPv6.
117If IPv4 addresses only are to be looked up then
118.Fa af
119should be set to
120.Dv AF_INET ,
121otherwise it should be set to
122.Dv AF_INET6 .
123.Pp
124There are three flags that can be set
125.Bl -tag -width "AI_ADDRCONFIG"
126.It Dv AI_V4MAPPED
127Return IPv4 addresses if no IPv6 addresses are found.
128This flag is ignored unless
129.Fa af
130is
131.Dv AF_INET6 .
132.It Dv AI_ALL
133Return IPv4 addresses as well IPv6 addresses if
134.Dv AI_V4MAPPED
135is set.
136This flag is ignored unless
137.Fa af
138is
139.Dv AF_INET6 .
140.It Dv AI_ADDRCONFIG
141Only return addresses of a given type if the system has an active interface
142with that type.
143.El
144.Pp
145Also
146.Dv AI_DEFAULT
147is defined to be
148.Dv (AI_V4MAPPED|AI_ADDRCONFIG) .
149.Pp
150.Fn Getipnodebyaddr
151will lookup IPv4 mapped and compatible addresses in the IPv4 name
152space and IPv6 name space
153.Pp
154.Fn Freehostent
155frees the hostent structure allocated be
156.Fn getipnodebyname
157and
158.Fn getipnodebyaddr .
159The structures returned by
160.Fn gethostbyname ,
161.Fn gethostbyname2 ,
162.Fn gethostbyaddr
163and
164.Fn gethostent
165should not be passed to
166.Fn freehostent
167as they are pointers to static areas.
168.Sh ENVIRONMENT
169.Bl -tag -width "HOSTALIASES  " -compact
170.It Ev HOSTALIASES
171Name of file containing
172.Pq Ar host alias , full hostname
173pairs.
174.El
175.Sh FILES
176.Bl -tag -width "HOSTALIASES  " -compact
177.It Pa /etc/hosts
178See
179.Xr hosts 5 .
180.El
181.Sh DIAGNOSTICS
182.Pp
183Error return status from
184.Fn getipnodebyname
185and
186.Fn getipnodebyaddr
187is indicated by return of a null pointer.
188In this case
189.Ft error
190may then be checked to see whether this is a temporary failure
191or an invalid or unknown host.
192.Ft errno
193can have the following values:
194.Bl -tag -width "HOST_NOT_FOUND  " -offset indent
195.It Dv NETDB_INTERNAL
196This indicates an internal error in the library, unrelated to the network
197or name service.
198.Ft errno
199will be valid in this case; see
200.Xr perror  .
201.It Dv HOST_NOT_FOUND
202No such host is known.
203.It Dv TRY_AGAIN
204This is usually a temporary error
205and means that the local server did not receive
206a response from an authoritative server.
207A retry at some later time may succeed.
208.It Dv NO_RECOVERY
209Some unexpected server failure was encountered.
210This is a non-recoverable error, as one might expect.
211.It Dv NO_ADDRESS
212The requested name is valid but does not have an IP address;
213this is not a temporary error.
214This means that the name is known to the name server but there is no address
215associated with this name.
216Another type of request to the name server using this domain name
217will result in an answer;
218for example, a mail-forwarder may be registered for this domain.
219.El
220.Sh SEE ALSO
221.Xr hosts 5 ,
222.Xr hostname 7 ,
223.Xr resolver 3 ,
224.Xr resolver 5 ,
225.Xr gethostbyname 3 ,
226.Xr RFC2553 .
227