]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
4 | .\" |
5 | .\" References: RFC 2553 | |
4c1c5274 | 6 | .TH getipnodebyname 3 (date) "Linux man-pages (unreleased)" |
fea681da | 7 | .SH NAME |
c13182ef | 8 | getipnodebyname, getipnodebyaddr, freehostent \- get network |
ddaec46d | 9 | hostnames and addresses |
42009080 AC |
10 | .SH LIBRARY |
11 | Standard C library | |
12 | .RI ( libc ", " \-lc ) | |
fea681da MK |
13 | .SH SYNOPSIS |
14 | .nf | |
15 | .B #include <sys/types.h> | |
16 | .B #include <sys/socket.h> | |
17 | .B #include <netdb.h> | |
68e4db0a | 18 | .PP |
8ae107aa AC |
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 , | |
22 | .BI " size_t " len ", int " af , | |
23 | .BI " int *" "error_num" ); | |
24 | .BI "[[deprecated]] void freehostent(struct hostent *" "ip" ); | |
fea681da MK |
25 | .fi |
26 | .SH DESCRIPTION | |
a5b9e015 | 27 | These functions are deprecated (and unavailable in glibc). |
c13182ef | 28 | Use |
fea681da MK |
29 | .BR getaddrinfo (3) |
30 | and | |
31 | .BR getnameinfo (3) | |
32 | instead. | |
dd3568a1 | 33 | .PP |
fea681da | 34 | The |
2777b1ca | 35 | .BR getipnodebyname () |
fea681da | 36 | and |
2777b1ca | 37 | .BR getipnodebyaddr () |
fea681da MK |
38 | functions return the names and addresses of a network host. |
39 | These functions return a pointer to the | |
40 | following structure: | |
51f5698d | 41 | .PP |
3ad4ddcd | 42 | .in +4n |
b8302363 | 43 | .EX |
4e836144 | 44 | struct hostent { |
89f9f5b2 MK |
45 | char *h_name; |
46 | char **h_aliases; | |
47 | int h_addrtype; | |
48 | int h_length; | |
49 | char **h_addr_list; | |
cf50b31d | 50 | }; |
b8302363 | 51 | .EE |
e646a1ba | 52 | .in |
fea681da MK |
53 | .PP |
54 | These functions replace the | |
55 | .BR gethostbyname (3) | |
56 | and | |
57 | .BR gethostbyaddr (3) | |
33a0ccb2 | 58 | functions, which could access only the IPv4 network address family. |
fea681da | 59 | The |
2777b1ca | 60 | .BR getipnodebyname () |
fea681da | 61 | and |
2777b1ca | 62 | .BR getipnodebyaddr () |
fea681da MK |
63 | functions can access multiple network address families. |
64 | .PP | |
65 | Unlike the | |
66 | .B gethostby | |
67 | functions, | |
f19a0f03 | 68 | these functions return pointers to dynamically allocated memory. |
fea681da | 69 | The |
2777b1ca | 70 | .BR freehostent () |
fea681da MK |
71 | function is used to release the dynamically allocated memory |
72 | after the caller no longer needs the | |
11003586 | 73 | .I hostent |
fea681da | 74 | structure. |
c4bb193f | 75 | .SS getipnodebyname() arguments |
fea681da | 76 | The |
2777b1ca | 77 | .BR getipnodebyname () |
fea681da MK |
78 | function |
79 | looks up network addresses for the host | |
80 | specified by the | |
81 | .I name | |
c4bb193f | 82 | argument. |
fea681da MK |
83 | The |
84 | .I af | |
c4bb193f | 85 | argument specifies one of the following values: |
fea681da MK |
86 | .TP |
87 | .B AF_INET | |
88 | The | |
89 | .I name | |
c4bb193f | 90 | argument points to a dotted-quad IPv4 address or a name |
fea681da MK |
91 | of an IPv4 network host. |
92 | .TP | |
93 | .B AF_INET6 | |
94 | The | |
95 | .I name | |
c4bb193f | 96 | argument points to a hexadecimal IPv6 address or a name |
fea681da MK |
97 | of an IPv6 network host. |
98 | .PP | |
99 | The | |
100 | .I flags | |
c4bb193f | 101 | argument specifies additional options. |
b7d6564b | 102 | More than one option can be specified by bitwise OR-ing |
fea681da MK |
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 | |
c13182ef | 134 | This flag is equivalent to |
fea681da | 135 | .BR "(AI_ADDRCONFIG | AI_V4MAPPED)" . |
c4bb193f | 136 | .SS getipnodebyaddr() arguments |
fea681da | 137 | The |
2777b1ca | 138 | .BR getipnodebyaddr () |
fea681da MK |
139 | function |
140 | looks up the name of the host whose | |
141 | network address is | |
142 | specified by the | |
143 | .I addr | |
c4bb193f | 144 | argument. |
fea681da MK |
145 | The |
146 | .I af | |
c4bb193f | 147 | argument specifies one of the following values: |
fea681da MK |
148 | .TP |
149 | .B AF_INET | |
150 | The | |
151 | .I addr | |
c4bb193f | 152 | argument points to a |
8478ee02 | 153 | .I struct in_addr |
fea681da MK |
154 | and |
155 | .I len | |
156 | must be set to | |
8478ee02 | 157 | .IR "sizeof(struct in_addr)" . |
fea681da MK |
158 | .TP |
159 | .B AF_INET6 | |
160 | The | |
161 | .I addr | |
c4bb193f | 162 | argument points to a |
8478ee02 | 163 | .I struct in6_addr |
fea681da MK |
164 | and |
165 | .I len | |
166 | must be set to | |
8478ee02 | 167 | .IR "sizeof(struct in6_addr)" . |
47297adb | 168 | .SH RETURN VALUE |
b437fdd9 | 169 | NULL is returned if an error occurred, and |
fea681da MK |
170 | .I error_num |
171 | will contain an error code from the following list: | |
172 | .TP | |
173 | .B HOST_NOT_FOUND | |
ddaec46d | 174 | The hostname or network address was not found. |
fea681da MK |
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 | .PP | |
189 | A successful query returns a pointer to a | |
11003586 | 190 | .I hostent |
fea681da MK |
191 | structure that contains the following fields: |
192 | .TP | |
11003586 | 193 | .I h_name |
fea681da MK |
194 | This is the official name of this network host. |
195 | .TP | |
11003586 | 196 | .I h_aliases |
fea681da | 197 | This is an array of pointers to unofficial aliases for the same host. |
b437fdd9 | 198 | The array is terminated by a null pointer. |
fea681da | 199 | .TP |
11003586 | 200 | .I h_addrtype |
fea681da MK |
201 | This is a copy of the |
202 | .I af | |
c4bb193f | 203 | argument to |
2777b1ca | 204 | .BR getipnodebyname () |
fea681da | 205 | or |
2777b1ca | 206 | .BR getipnodebyaddr (). |
fea681da MK |
207 | .I h_addrtype |
208 | will always be | |
209 | .B AF_INET | |
210 | if the | |
211 | .I af | |
c4bb193f | 212 | argument was |
fea681da MK |
213 | .BR AF_INET . |
214 | .I h_addrtype | |
215 | will always be | |
216 | .B AF_INET6 | |
217 | if the | |
218 | .I af | |
c4bb193f | 219 | argument was |
fea681da MK |
220 | .BR AF_INET6 . |
221 | .TP | |
11003586 | 222 | .I h_length |
fea681da | 223 | This field will be set to |
8478ee02 | 224 | .I sizeof(struct in_addr) |
fea681da MK |
225 | if |
226 | .I h_addrtype | |
2f0af33b MK |
227 | is |
228 | .BR AF_INET , | |
229 | and to | |
8478ee02 | 230 | .I sizeof(struct in6_addr) |
fea681da MK |
231 | if |
232 | .I h_addrtype | |
2f0af33b MK |
233 | is |
234 | .BR AF_INET6 . | |
fea681da | 235 | .TP |
11003586 | 236 | .I h_addr_list |
fea681da MK |
237 | This is an array of one or more pointers to network address structures for the |
238 | network host. | |
b437fdd9 | 239 | The array is terminated by a null pointer. |
3113c7f3 | 240 | .SH STANDARDS |
2b2581ee MK |
241 | RFC\ 2553. |
242 | .\" Not in POSIX.1-2001. | |
fea681da | 243 | .SH NOTES |
881f6c4a | 244 | These functions were present in glibc 2.1.91-95, but were |
c13182ef | 245 | removed again. |
008f1ecc | 246 | Several UNIX-like systems support them, but all |
fea681da | 247 | call them deprecated. |
47297adb | 248 | .SH SEE ALSO |
fea681da MK |
249 | .BR getaddrinfo (3), |
250 | .BR getnameinfo (3), | |
251 | .BR inet_ntop (3), | |
252 | .BR inet_pton (3) |