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