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