| blob | 09808542b1f519e4a69444d8d733666f0e4d9ed3 |
1 .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" References: RFC 2553
6 .TH getipnodebyname 3 (date) "Linux man-pages (unreleased)"
7 .SH NAME
8 getipnodebyname, getipnodebyaddr, freehostent \- get network
9 hostnames and addresses
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ", " \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/types.h>
16 .B #include <sys/socket.h>
17 .B #include <netdb.h>
18 .P
19 .BI "[[deprecated]] struct hostent *getipnodebyname(const char *" name ", int " af ,
20 .BI " int " flags ", int *" error_num );
21 .BI "[[deprecated]] struct hostent *getipnodebyaddr(const void " addr [. len ],
22 .BI " size_t " len ", int " af ,
23 .BI " int *" "error_num" );
24 .BI "[[deprecated]] void freehostent(struct hostent *" "ip" );
25 .fi
26 .SH DESCRIPTION
27 These functions are deprecated (and unavailable in glibc).
28 Use
29 .BR getaddrinfo (3)
30 and
31 .BR getnameinfo (3)
32 instead.
33 .P
34 The
35 .BR getipnodebyname ()
36 and
37 .BR getipnodebyaddr ()
38 functions return the names and addresses of a network host.
39 These functions return a pointer to the
40 following structure:
41 .P
42 .in +4n
43 .EX
44 struct hostent {
45 char *h_name;
46 char **h_aliases;
47 int h_addrtype;
48 int h_length;
49 char **h_addr_list;
50 };
51 .EE
52 .in
53 .P
54 These functions replace the
55 .BR gethostbyname (3)
56 and
57 .BR gethostbyaddr (3)
58 functions, which could access only the IPv4 network address family.
59 The
60 .BR getipnodebyname ()
61 and
62 .BR getipnodebyaddr ()
63 functions can access multiple network address families.
64 .P
65 Unlike the
66 .B gethostby
67 functions,
68 these functions return pointers to dynamically allocated memory.
69 The
70 .BR freehostent ()
71 function is used to release the dynamically allocated memory
72 after the caller no longer needs the
73 .I hostent
74 structure.
75 .SS getipnodebyname() arguments
76 The
77 .BR getipnodebyname ()
78 function
79 looks up network addresses for the host
80 specified by the
81 .I name
82 argument.
83 The
84 .I af
85 argument specifies one of the following values:
86 .TP
87 .B AF_INET
88 The
89 .I name
90 argument points to a dotted-quad IPv4 address or a name
91 of an IPv4 network host.
92 .TP
93 .B AF_INET6
94 The
95 .I name
96 argument points to a hexadecimal IPv6 address or a name
97 of an IPv6 network host.
98 .P
99 The
100 .I flags
101 argument specifies additional options.
102 More than one option can be specified by bitwise OR-ing
103 them together.
104 .I flags
105 should be set to 0
106 if no options are desired.
107 .TP
108 .B AI_V4MAPPED
109 This flag is used with
110 .B AF_INET6
111 to request a query for IPv4 addresses instead of
112 IPv6 addresses; the IPv4 addresses will
113 be mapped to IPv6 addresses.
114 .TP
115 .B AI_ALL
116 This flag is used with
117 .B AI_V4MAPPED
118 to request a query for both IPv4 and IPv6 addresses.
119 Any IPv4 address found will be mapped to an IPv6 address.
120 .TP
121 .B AI_ADDRCONFIG
122 This flag is used with
123 .B AF_INET6
124 to
125 further request that queries for IPv6 addresses should not be made unless
126 the system has at least one IPv6 address assigned to a network interface,
127 and that queries for IPv4 addresses should not be made unless the
128 system has at least one IPv4 address assigned to a network interface.
129 This flag may be used by itself or with the
130 .B AI_V4MAPPED
131 flag.
132 .TP
133 .B AI_DEFAULT
134 This flag is equivalent to
135 .BR "(AI_ADDRCONFIG | AI_V4MAPPED)" .
136 .SS getipnodebyaddr() arguments
137 The
138 .BR getipnodebyaddr ()
139 function
140 looks up the name of the host whose
141 network address is
142 specified by the
143 .I addr
144 argument.
145 The
146 .I af
147 argument specifies one of the following values:
148 .TP
149 .B AF_INET
150 The
151 .I addr
152 argument points to a
153 .I struct in_addr
154 and
155 .I len
156 must be set to
157 .IR "sizeof(struct in_addr)" .
158 .TP
159 .B AF_INET6
160 The
161 .I addr
162 argument points to a
163 .I struct in6_addr
164 and
165 .I len
166 must be set to
167 .IR "sizeof(struct in6_addr)" .
168 .SH RETURN VALUE
169 NULL is returned if an error occurred, and
170 .I error_num
171 will contain an error code from the following list:
172 .TP
173 .B HOST_NOT_FOUND
174 The hostname or network address was not found.
175 .TP
176 .B NO_ADDRESS
177 The domain name server recognized the network address or name,
178 but no answer was returned.
179 This can happen if the network host has only IPv4 addresses and
180 a request has been made for IPv6 information only, or vice versa.
181 .TP
182 .B NO_RECOVERY
183 The domain name server returned a permanent failure response.
184 .TP
185 .B TRY_AGAIN
186 The domain name server returned a temporary failure response.
187 You might have better luck next time.
188 .P
189 A successful query returns a pointer to a
190 .I hostent
191 structure that contains the following fields:
192 .TP
193 .I h_name
194 This is the official name of this network host.
195 .TP
196 .I h_aliases
197 This is an array of pointers to unofficial aliases for the same host.
198 The array is terminated by a null pointer.
199 .TP
200 .I h_addrtype
201 This is a copy of the
202 .I af
203 argument to
204 .BR getipnodebyname ()
205 or
206 .BR getipnodebyaddr ().
207 .I h_addrtype
208 will always be
209 .B AF_INET
210 if the
211 .I af
212 argument was
213 .BR AF_INET .
214 .I h_addrtype
215 will always be
216 .B AF_INET6
217 if the
218 .I af
219 argument was
220 .BR AF_INET6 .
221 .TP
222 .I h_length
223 This field will be set to
224 .I sizeof(struct in_addr)
225 if
226 .I h_addrtype
227 is
228 .BR AF_INET ,
229 and to
230 .I sizeof(struct in6_addr)
231 if
232 .I h_addrtype
233 is
234 .BR AF_INET6 .
235 .TP
236 .I h_addr_list
237 This is an array of one or more pointers to network address structures for the
238 network host.
239 The array is terminated by a null pointer.
240 .SH STANDARDS
241 None.
242 .SH HISTORY
243 .\" Not in POSIX.1-2001.
244 RFC\ 2553.
245 .P
246 Present in glibc 2.1.91-95, but removed again.
247 Several UNIX-like systems support them, but all
248 call them deprecated.
249 .SH SEE ALSO
250 .BR getaddrinfo (3),
251 .BR getnameinfo (3),
252 .BR inet_ntop (3),
253 .BR inet_pton (3)