]>
Commit | Line | Data |
---|---|---|
2d6c6dd1 | 1 | .\" %%%LICENSE_START(PUBLIC_DOMAIN) |
fea681da | 2 | .\" This page is in the public domain. |
2d6c6dd1 | 3 | .\" %%%LICENSE_END |
9f9c6de1 | 4 | .\" |
fea681da MK |
5 | .\" Almost all details are from RFC 2553. |
6 | .\" | |
3d4d9116 MK |
7 | .\" 2004-12-14, mtk, Added EAI_OVERFLOW error |
8 | .\" 2004-12-14 Fixed description of error return | |
9 | .\" | |
9ba01802 | 10 | .TH GETNAMEINFO 3 2019-03-06 "GNU" "Linux Programmer's Manual" |
fea681da MK |
11 | .SH NAME |
12 | getnameinfo \- address-to-name translation in protocol-independent manner | |
13 | .SH SYNOPSIS | |
14 | .nf | |
15 | .B #include <sys/socket.h> | |
16 | .B #include <netdb.h> | |
68e4db0a | 17 | .PP |
24a31d63 | 18 | .BI "int getnameinfo(const struct sockaddr *" "addr" ", socklen_t " "addrlen" , |
7c1e49d2 RV |
19 | .BI " char *" "host" ", socklen_t " "hostlen" , |
20 | .BI " char *" "serv" ", socklen_t " "servlen" ", int " "flags" ); | |
fea681da | 21 | .fi |
68e4db0a | 22 | .PP |
0f200f07 MK |
23 | .in -4n |
24 | Feature Test Macro Requirements for glibc (see | |
25 | .BR feature_test_macros (7)): | |
26 | .ad l | |
27 | .in | |
68e4db0a | 28 | .PP |
0f200f07 | 29 | .BR getnameinfo (): |
852d92f7 MK |
30 | Since glibc 2.22: _POSIX_C_SOURCE >= 201112L |
31 | Glibc 2.21 and earlier: _POSIX_C_SOURCE | |
0f200f07 | 32 | .ad b |
fea681da MK |
33 | .SH DESCRIPTION |
34 | The | |
2777b1ca | 35 | .BR getnameinfo () |
c81e8a42 MK |
36 | function is the inverse of |
37 | .BR getaddrinfo (3): | |
38 | it converts a socket address to a corresponding host and service, | |
39 | in a protocol-independent manner. | |
fea681da MK |
40 | It combines the functionality of |
41 | .BR gethostbyaddr (3) | |
42 | and | |
c81e8a42 MK |
43 | .BR getservbyport (3), |
44 | but unlike those functions, | |
27a6247b | 45 | .BR getnameinfo () |
c81e8a42 MK |
46 | is reentrant and allows programs to eliminate |
47 | IPv4-versus-IPv6 dependencies. | |
847e0d88 | 48 | .PP |
fea681da | 49 | The |
75970bd6 | 50 | .I addr |
fea681da MK |
51 | argument is a pointer to a generic socket address structure |
52 | (of type | |
53 | .I sockaddr_in | |
54 | or | |
55 | .IR sockaddr_in6 ) | |
56 | of size | |
24a31d63 | 57 | .I addrlen |
fea681da MK |
58 | that holds the input IP address and port number. |
59 | The arguments | |
60 | .I host | |
61 | and | |
62 | .I serv | |
c81e8a42 | 63 | are pointers to caller-allocated buffers (of size |
fea681da MK |
64 | .I hostlen |
65 | and | |
66 | .I servlen | |
c81e8a42 MK |
67 | respectively) into which |
68 | .BR getnameinfo () | |
69 | places null-terminated strings containing the host and | |
70 | service names respectively. | |
847e0d88 | 71 | .PP |
fea681da MK |
72 | The caller can specify that no hostname (or no service name) |
73 | is required by providing a NULL | |
74 | .I host | |
75 | (or | |
76 | .IR serv ) | |
77 | argument or a zero | |
78 | .I hostlen | |
79 | (or | |
80 | .IR servlen ) | |
c81e8a42 | 81 | argument. |
c13182ef | 82 | However, at least one of hostname or service name |
fea681da | 83 | must be requested. |
847e0d88 | 84 | .PP |
fea681da MK |
85 | The |
86 | .I flags | |
d9bfdb9c | 87 | argument modifies the behavior of |
2777b1ca | 88 | .BR getnameinfo () |
fea681da MK |
89 | as follows: |
90 | .TP | |
c81e8a42 MK |
91 | .B NI_NAMEREQD |
92 | If set, then an error is returned if the hostname cannot be determined. | |
93 | .TP | |
94 | .B NI_DGRAM | |
95 | If set, then the service is datagram (UDP) based rather than | |
96 | stream (TCP) based. | |
9bc87ed0 | 97 | This is required for the few ports (512\(en514) |
c81e8a42 MK |
98 | that have different services for UDP and TCP. |
99 | .TP | |
fea681da | 100 | .B NI_NOFQDN |
c81e8a42 MK |
101 | If set, return only the hostname part of the fully qualified domain name |
102 | for local hosts. | |
fea681da MK |
103 | .TP |
104 | .B NI_NUMERICHOST | |
105 | If set, then the numeric form of the hostname is returned. | |
106 | .\" For example, by calling | |
ef1ee33c | 107 | .\" .BR inet_ntop () |
fea681da | 108 | .\" instead of |
ef1ee33c | 109 | .\" .BR gethostbyaddr (). |
fea681da | 110 | (When not set, this will still happen in case the node's name |
c81e8a42 MK |
111 | cannot be determined.) |
112 | .\" POSIX.1-2003 has NI_NUMERICSCOPE, but glibc doesn't have it. | |
fea681da MK |
113 | .TP |
114 | .B NI_NUMERICSERV | |
c81e8a42 MK |
115 | If set, then the numeric form of the service address is returned. |
116 | (When not set, this will still happen in case the service's name | |
117 | cannot be determined.) | |
73d8cece | 118 | .SS Extensions to getnameinfo() for Internationalized Domain Names |
22135cad MK |
119 | .PP |
120 | Starting with glibc 2.3.4, | |
c13182ef | 121 | .BR getnameinfo () |
22135cad | 122 | has been extended to selectively allow |
ddaec46d | 123 | hostnames to be transparently converted to and from the |
22135cad MK |
124 | Internationalized Domain Name (IDN) format (see RFC 3490, |
125 | .IR "Internationalizing Domain Names in Applications (IDNA)" ). | |
126 | Three new flags are defined: | |
127 | .TP | |
128 | .B NI_IDN | |
129 | If this flag is used, then the name found in the lookup process is | |
c13182ef | 130 | converted from IDN format to the locale's encoding if necessary. |
22135cad MK |
131 | ASCII-only names are not affected by the conversion, which |
132 | makes this flag usable in existing programs and environments. | |
133 | .TP | |
134 | .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES | |
c13182ef | 135 | Setting these flags will enable the |
22135cad | 136 | IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and |
c13182ef | 137 | IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 |
ddaec46d | 138 | conforming hostname) |
22135cad | 139 | flags respectively to be used in the IDNA handling. |
47297adb | 140 | .SH RETURN VALUE |
420dad7a | 141 | .\" FIXME glibc defines the following additional errors, some which |
c13182ef | 142 | .\" can probably be returned by getnameinfo(); they need to |
420dad7a | 143 | .\" be documented. |
9c7bd103 MK |
144 | .\" |
145 | .\" #ifdef __USE_GNU | |
146 | .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ | |
147 | .\" #define EAI_CANCELED -101 /* Request canceled. */ | |
148 | .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ | |
149 | .\" #define EAI_ALLDONE -103 /* All requests done. */ | |
150 | .\" #define EAI_INTR -104 /* Interrupted by a signal. */ | |
151 | .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ | |
152 | .\" #endif | |
60569afd | 153 | On success, 0 is returned, and node and service names, if requested, |
28d88c17 | 154 | are filled with null-terminated strings, possibly truncated to fit |
fea681da | 155 | the specified buffer lengths. |
dec985f9 | 156 | On error, one of the following nonzero error codes is returned: |
fea681da MK |
157 | .TP |
158 | .B EAI_AGAIN | |
c13182ef MK |
159 | The name could not be resolved at this time. |
160 | Try again later. | |
fea681da MK |
161 | .TP |
162 | .B EAI_BADFLAGS | |
163 | The | |
164 | .I flags | |
c81e8a42 | 165 | argument has an invalid value. |
fea681da MK |
166 | .TP |
167 | .B EAI_FAIL | |
b28f6e56 | 168 | A nonrecoverable error occurred. |
fea681da MK |
169 | .TP |
170 | .B EAI_FAMILY | |
171 | The address family was not recognized, | |
172 | or the address length was invalid for the specified family. | |
173 | .TP | |
174 | .B EAI_MEMORY | |
175 | Out of memory. | |
176 | .TP | |
177 | .B EAI_NONAME | |
c81e8a42 | 178 | The name does not resolve for the supplied arguments. |
2f0af33b MK |
179 | .B NI_NAMEREQD |
180 | is set and the host's name cannot be located, | |
fea681da MK |
181 | or neither hostname nor service name were requested. |
182 | .TP | |
3d4d9116 MK |
183 | .B EAI_OVERFLOW |
184 | The buffer pointed to by | |
185 | .I host | |
186 | or | |
187 | .I serv | |
188 | was too small. | |
189 | .TP | |
fea681da | 190 | .B EAI_SYSTEM |
c13182ef MK |
191 | A system error occurred. |
192 | The error code can be found in | |
fea681da | 193 | .IR errno . |
6a7f0c48 | 194 | .PP |
d2cf9489 MK |
195 | The |
196 | .BR gai_strerror (3) | |
197 | function translates these error codes to a human readable string, | |
198 | suitable for error reporting. | |
fea681da | 199 | .SH FILES |
7ebb909a | 200 | .I /etc/hosts |
fea681da | 201 | .br |
7ebb909a | 202 | .I /etc/nsswitch.conf |
fea681da | 203 | .br |
7ebb909a | 204 | .I /etc/resolv.conf |
c343e74c MK |
205 | .SH VERSIONS |
206 | .BR getnameinfo () | |
207 | is provided in glibc since version 2.1. | |
a9e30c8c ZL |
208 | .SH ATTRIBUTES |
209 | For an explanation of the terms used in this section, see | |
210 | .BR attributes (7). | |
211 | .TS | |
212 | allbox; | |
213 | lb lb lb | |
214 | l l l. | |
215 | Interface Attribute Value | |
216 | T{ | |
217 | .BR getnameinfo () | |
218 | T} Thread safety MT-Safe env locale | |
219 | .TE | |
847e0d88 | 220 | .sp 1 |
47297adb | 221 | .SH CONFORMING TO |
0281851d | 222 | POSIX.1-2001, POSIX.1-2008, RFC\ 2553. |
19c98696 | 223 | .SH NOTES |
fea681da MK |
224 | In order to assist the programmer in choosing reasonable sizes |
225 | for the supplied buffers, | |
226 | .I <netdb.h> | |
227 | defines the constants | |
e646a1ba | 228 | .PP |
088a639b | 229 | .in +4n |
e646a1ba | 230 | .EX |
3d32fee8 MK |
231 | #define NI_MAXHOST 1025 |
232 | #define NI_MAXSERV 32 | |
b8302363 | 233 | .EE |
6602f61c | 234 | .in |
847e0d88 | 235 | .PP |
0d4b699d | 236 | Since glibc 2.8, |
d59161f9 MK |
237 | these definitions are exposed only if suitable |
238 | feature test macros are defined, namely: | |
239 | .BR _GNU_SOURCE , | |
240 | .BR _DEFAULT_SOURCE | |
241 | (since glibc 2.19), | |
242 | or (in glibc versions up to and including 2.19) | |
243 | .BR _BSD_SOURCE | |
0d4b699d | 244 | or |
d59161f9 | 245 | .BR _SVID_SOURCE . |
6602f61c | 246 | .PP |
2f0af33b MK |
247 | The former is the constant |
248 | .B MAXDNAME | |
249 | in recent versions of BIND's | |
fea681da | 250 | .I <arpa/nameser.h> |
c13182ef MK |
251 | header file. |
252 | The latter is a guess based on the services listed | |
fea681da | 253 | in the current Assigned Numbers RFC. |
847e0d88 | 254 | .PP |
c15f85d8 MK |
255 | Before glibc version 2.2, the |
256 | .I hostlen | |
257 | and | |
258 | .I servlen | |
259 | arguments were typed as | |
260 | .IR size_t . | |
9b336505 | 261 | .SH EXAMPLE |
6602f61c MK |
262 | The following code tries to get the numeric hostname and service name, |
263 | for a given socket address. | |
c13182ef | 264 | Note that there is no hardcoded reference to |
fea681da | 265 | a particular address family. |
847e0d88 | 266 | .PP |
088a639b | 267 | .in +4n |
b8302363 | 268 | .EX |
24a31d63 MK |
269 | struct sockaddr *addr; /* input */ |
270 | socklen_t addrlen; /* input */ | |
6602f61c | 271 | char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; |
fea681da | 272 | |
24a31d63 | 273 | if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf, |
6602f61c | 274 | sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) |
31a6818e | 275 | printf("host=%s, serv=%s\en", hbuf, sbuf); |
b8302363 | 276 | .EE |
6602f61c | 277 | .in |
847e0d88 | 278 | .PP |
fea681da MK |
279 | The following version checks if the socket address has a |
280 | reverse address mapping. | |
847e0d88 | 281 | .PP |
088a639b | 282 | .in +4n |
b8302363 | 283 | .EX |
24a31d63 MK |
284 | struct sockaddr *addr; /* input */ |
285 | socklen_t addrlen; /* input */ | |
6602f61c | 286 | char hbuf[NI_MAXHOST]; |
fea681da | 287 | |
24a31d63 | 288 | if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), |
6602f61c MK |
289 | NULL, 0, NI_NAMEREQD)) |
290 | printf("could not resolve hostname"); | |
291 | else | |
31a6818e | 292 | printf("host=%s\en", hbuf); |
b8302363 | 293 | .EE |
6602f61c | 294 | .in |
77dbc341 | 295 | .PP |
6602f61c | 296 | An example program using |
77dbc341 MK |
297 | .BR getnameinfo () |
298 | can be found in | |
299 | .BR getaddrinfo (3). | |
47297adb | 300 | .SH SEE ALSO |
c81e8a42 MK |
301 | .BR accept (2), |
302 | .BR getpeername (2), | |
303 | .BR getsockname (2), | |
304 | .BR recvfrom (2), | |
2f1f4221 | 305 | .BR socket (2), |
fea681da MK |
306 | .BR getaddrinfo (3), |
307 | .BR gethostbyaddr (3), | |
308 | .BR getservbyname (3), | |
309 | .BR getservbyport (3), | |
310 | .BR inet_ntop (3), | |
fea681da MK |
311 | .BR hosts (5), |
312 | .BR services (5), | |
313 | .BR hostname (7), | |
314 | .BR named (8) | |
847e0d88 | 315 | .PP |
8fb01fde | 316 | R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens, |
fea681da | 317 | .IR "Basic Socket Interface Extensions for IPv6" , |
331da7c3 | 318 | RFC\ 2553, March 1999. |
847e0d88 | 319 | .PP |
fea681da MK |
320 | Tatsuya Jinmei and Atsushi Onoe, |
321 | .IR "An Extension of Format for IPv6 Scoped Addresses" , | |
173fe7e7 | 322 | internet draft, work in progress |
608bf950 | 323 | .UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt |
173fe7e7 | 324 | .UE . |
847e0d88 | 325 | .PP |
fea681da MK |
326 | Craig Metz, |
327 | .IR "Protocol Independence Using the Sockets API" , | |
328 | Proceedings of the freenix track: | |
173fe7e7 | 329 | 2000 USENIX annual technical conference, June 2000 |
d0f1fd33 | 330 | .ad l |
608bf950 | 331 | .UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html |
173fe7e7 | 332 | .UE . |