]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" References: RFC 2553 | |
4b8c67d9 | 26 | .TH GETIPNODEBYNAME 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 27 | .SH NAME |
c13182ef | 28 | getipnodebyname, getipnodebyaddr, freehostent \- get network |
ddaec46d | 29 | hostnames and addresses |
fea681da MK |
30 | .SH SYNOPSIS |
31 | .nf | |
32 | .B #include <sys/types.h> | |
33 | .B #include <sys/socket.h> | |
34 | .B #include <netdb.h> | |
68e4db0a | 35 | .PP |
62218dc0 MK |
36 | .BI "struct hostent *getipnodebyname(const char *" name ", int " af , |
37 | .BI " int " flags ", int *" error_num ); | |
68e4db0a | 38 | .PP |
62218dc0 | 39 | .BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len , |
eaa88fd8 | 40 | .BI " int " af ", int *" "error_num" ); |
68e4db0a | 41 | .PP |
fea681da MK |
42 | .BI "void freehostent(struct hostent *" "ip" ); |
43 | .fi | |
44 | .SH DESCRIPTION | |
a5b9e015 | 45 | These functions are deprecated (and unavailable in glibc). |
c13182ef | 46 | Use |
fea681da MK |
47 | .BR getaddrinfo (3) |
48 | and | |
49 | .BR getnameinfo (3) | |
50 | instead. | |
dd3568a1 | 51 | .PP |
fea681da | 52 | The |
2777b1ca | 53 | .BR getipnodebyname () |
fea681da | 54 | and |
2777b1ca | 55 | .BR getipnodebyaddr () |
fea681da MK |
56 | functions return the names and addresses of a network host. |
57 | These functions return a pointer to the | |
58 | following structure: | |
51f5698d | 59 | .PP |
3ad4ddcd | 60 | .in +4n |
b8302363 | 61 | .EX |
4e836144 | 62 | struct hostent { |
89f9f5b2 MK |
63 | char *h_name; |
64 | char **h_aliases; | |
65 | int h_addrtype; | |
66 | int h_length; | |
67 | char **h_addr_list; | |
cf50b31d | 68 | }; |
b8302363 | 69 | .EE |
e646a1ba | 70 | .in |
fea681da MK |
71 | .PP |
72 | These functions replace the | |
73 | .BR gethostbyname (3) | |
74 | and | |
75 | .BR gethostbyaddr (3) | |
33a0ccb2 | 76 | functions, which could access only the IPv4 network address family. |
fea681da | 77 | The |
2777b1ca | 78 | .BR getipnodebyname () |
fea681da | 79 | and |
2777b1ca | 80 | .BR getipnodebyaddr () |
fea681da MK |
81 | functions can access multiple network address families. |
82 | .PP | |
83 | Unlike the | |
84 | .B gethostby | |
85 | functions, | |
f19a0f03 | 86 | these functions return pointers to dynamically allocated memory. |
fea681da | 87 | The |
2777b1ca | 88 | .BR freehostent () |
fea681da MK |
89 | function is used to release the dynamically allocated memory |
90 | after the caller no longer needs the | |
11003586 | 91 | .I hostent |
fea681da | 92 | structure. |
c4bb193f | 93 | .SS getipnodebyname() arguments |
fea681da | 94 | The |
2777b1ca | 95 | .BR getipnodebyname () |
fea681da MK |
96 | function |
97 | looks up network addresses for the host | |
98 | specified by the | |
99 | .I name | |
c4bb193f | 100 | argument. |
fea681da MK |
101 | The |
102 | .I af | |
c4bb193f | 103 | argument specifies one of the following values: |
fea681da MK |
104 | .TP |
105 | .B AF_INET | |
106 | The | |
107 | .I name | |
c4bb193f | 108 | argument points to a dotted-quad IPv4 address or a name |
fea681da MK |
109 | of an IPv4 network host. |
110 | .TP | |
111 | .B AF_INET6 | |
112 | The | |
113 | .I name | |
c4bb193f | 114 | argument points to a hexadecimal IPv6 address or a name |
fea681da MK |
115 | of an IPv6 network host. |
116 | .PP | |
117 | The | |
118 | .I flags | |
c4bb193f | 119 | argument specifies additional options. |
b7d6564b | 120 | More than one option can be specified by bitwise OR-ing |
fea681da MK |
121 | them together. |
122 | .I flags | |
123 | should be set to 0 | |
124 | if no options are desired. | |
125 | .TP | |
126 | .B AI_V4MAPPED | |
127 | This flag is used with | |
128 | .B AF_INET6 | |
129 | to request a query for IPv4 addresses instead of | |
130 | IPv6 addresses; the IPv4 addresses will | |
131 | be mapped to IPv6 addresses. | |
132 | .TP | |
133 | .B AI_ALL | |
134 | This flag is used with | |
135 | .B AI_V4MAPPED | |
136 | to request a query for both IPv4 and IPv6 addresses. | |
137 | Any IPv4 address found will be mapped to an IPv6 address. | |
138 | .TP | |
139 | .B AI_ADDRCONFIG | |
140 | This flag is used with | |
141 | .B AF_INET6 | |
142 | to | |
143 | further request that queries for IPv6 addresses should not be made unless | |
144 | the system has at least one IPv6 address assigned to a network interface, | |
145 | and that queries for IPv4 addresses should not be made unless the | |
146 | system has at least one IPv4 address assigned to a network interface. | |
147 | This flag may be used by itself or with the | |
148 | .B AI_V4MAPPED | |
149 | flag. | |
150 | .TP | |
151 | .B AI_DEFAULT | |
c13182ef | 152 | This flag is equivalent to |
fea681da | 153 | .BR "(AI_ADDRCONFIG | AI_V4MAPPED)" . |
c4bb193f | 154 | .SS getipnodebyaddr() arguments |
fea681da | 155 | The |
2777b1ca | 156 | .BR getipnodebyaddr () |
fea681da MK |
157 | function |
158 | looks up the name of the host whose | |
159 | network address is | |
160 | specified by the | |
161 | .I addr | |
c4bb193f | 162 | argument. |
fea681da MK |
163 | The |
164 | .I af | |
c4bb193f | 165 | argument specifies one of the following values: |
fea681da MK |
166 | .TP |
167 | .B AF_INET | |
168 | The | |
169 | .I addr | |
c4bb193f | 170 | argument points to a |
8478ee02 | 171 | .I struct in_addr |
fea681da MK |
172 | and |
173 | .I len | |
174 | must be set to | |
8478ee02 | 175 | .IR "sizeof(struct in_addr)" . |
fea681da MK |
176 | .TP |
177 | .B AF_INET6 | |
178 | The | |
179 | .I addr | |
c4bb193f | 180 | argument points to a |
8478ee02 | 181 | .I struct in6_addr |
fea681da MK |
182 | and |
183 | .I len | |
184 | must be set to | |
8478ee02 | 185 | .IR "sizeof(struct in6_addr)" . |
47297adb | 186 | .SH RETURN VALUE |
b437fdd9 | 187 | NULL is returned if an error occurred, and |
fea681da MK |
188 | .I error_num |
189 | will contain an error code from the following list: | |
190 | .TP | |
191 | .B HOST_NOT_FOUND | |
ddaec46d | 192 | The hostname or network address was not found. |
fea681da MK |
193 | .TP |
194 | .B NO_ADDRESS | |
195 | The domain name server recognized the network address or name, | |
196 | but no answer was returned. | |
197 | This can happen if the network host has only IPv4 addresses and | |
198 | a request has been made for IPv6 information only, or vice versa. | |
199 | .TP | |
200 | .B NO_RECOVERY | |
201 | The domain name server returned a permanent failure response. | |
202 | .TP | |
203 | .B TRY_AGAIN | |
204 | The domain name server returned a temporary failure response. | |
205 | You might have better luck next time. | |
206 | .PP | |
207 | A successful query returns a pointer to a | |
11003586 | 208 | .I hostent |
fea681da MK |
209 | structure that contains the following fields: |
210 | .TP | |
11003586 | 211 | .I h_name |
fea681da MK |
212 | This is the official name of this network host. |
213 | .TP | |
11003586 | 214 | .I h_aliases |
fea681da | 215 | This is an array of pointers to unofficial aliases for the same host. |
b437fdd9 | 216 | The array is terminated by a null pointer. |
fea681da | 217 | .TP |
11003586 | 218 | .I h_addrtype |
fea681da MK |
219 | This is a copy of the |
220 | .I af | |
c4bb193f | 221 | argument to |
2777b1ca | 222 | .BR getipnodebyname () |
fea681da | 223 | or |
2777b1ca | 224 | .BR getipnodebyaddr (). |
fea681da MK |
225 | .I h_addrtype |
226 | will always be | |
227 | .B AF_INET | |
228 | if the | |
229 | .I af | |
c4bb193f | 230 | argument was |
fea681da MK |
231 | .BR AF_INET . |
232 | .I h_addrtype | |
233 | will always be | |
234 | .B AF_INET6 | |
235 | if the | |
236 | .I af | |
c4bb193f | 237 | argument was |
fea681da MK |
238 | .BR AF_INET6 . |
239 | .TP | |
11003586 | 240 | .I h_length |
fea681da | 241 | This field will be set to |
8478ee02 | 242 | .I sizeof(struct in_addr) |
fea681da MK |
243 | if |
244 | .I h_addrtype | |
2f0af33b MK |
245 | is |
246 | .BR AF_INET , | |
247 | and to | |
8478ee02 | 248 | .I sizeof(struct in6_addr) |
fea681da MK |
249 | if |
250 | .I h_addrtype | |
2f0af33b MK |
251 | is |
252 | .BR AF_INET6 . | |
fea681da | 253 | .TP |
11003586 | 254 | .I h_addr_list |
fea681da MK |
255 | This is an array of one or more pointers to network address structures for the |
256 | network host. | |
b437fdd9 | 257 | The array is terminated by a null pointer. |
47297adb | 258 | .SH CONFORMING TO |
2b2581ee MK |
259 | RFC\ 2553. |
260 | .\" Not in POSIX.1-2001. | |
fea681da | 261 | .SH NOTES |
881f6c4a | 262 | These functions were present in glibc 2.1.91-95, but were |
c13182ef | 263 | removed again. |
008f1ecc | 264 | Several UNIX-like systems support them, but all |
fea681da | 265 | call them deprecated. |
47297adb | 266 | .SH SEE ALSO |
fea681da MK |
267 | .BR getaddrinfo (3), |
268 | .BR getnameinfo (3), | |
269 | .BR inet_ntop (3), | |
270 | .BR inet_pton (3) |