Debian Codegraph @

upstream/debian-unstable/man3/getipnodebyname.3

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