]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" This page is in the public domain. |
2 | .\" Almost all details are from RFC 2553. | |
3 | .\" | |
3d4d9116 MK |
4 | .\" 2004-12-14, mtk, Added EAI_OVERFLOW error |
5 | .\" 2004-12-14 Fixed description of error return | |
6 | .\" | |
cb5f1a35 | 7 | .TH GETNAMEINFO 3 2007-06-08 "GNU" "Linux Programmer's Manual" |
fea681da MK |
8 | .SH NAME |
9 | getnameinfo \- address-to-name translation in protocol-independent manner | |
10 | .SH SYNOPSIS | |
11 | .nf | |
12 | .B #include <sys/socket.h> | |
13 | .B #include <netdb.h> | |
14 | .sp | |
15 | .BI "int getnameinfo(const struct sockaddr *" "sa" ", socklen_t " "salen" , | |
16 | .BI " char *" "host" ", size_t " "hostlen" , | |
17 | .BI " char *" "serv" ", size_t " "servlen" ", int " "flags" ); | |
18 | .fi | |
19 | .SH DESCRIPTION | |
20 | The | |
2777b1ca | 21 | .BR getnameinfo () |
fea681da MK |
22 | function is defined for protocol-independent address-to-nodename translation. |
23 | It combines the functionality of | |
24 | .BR gethostbyaddr (3) | |
25 | and | |
26 | .BR getservbyport (3) | |
27 | and is the inverse of | |
28 | .BR getaddrinfo (3). | |
29 | The | |
30 | .I sa | |
31 | argument is a pointer to a generic socket address structure | |
32 | (of type | |
33 | .I sockaddr_in | |
34 | or | |
35 | .IR sockaddr_in6 ) | |
36 | of size | |
0daa9e92 | 37 | .I salen |
fea681da MK |
38 | that holds the input IP address and port number. |
39 | The arguments | |
40 | .I host | |
41 | and | |
42 | .I serv | |
43 | are pointers to buffers (of size | |
44 | .I hostlen | |
45 | and | |
46 | .I servlen | |
47 | respectively) to hold the return values. | |
48 | ||
49 | The caller can specify that no hostname (or no service name) | |
50 | is required by providing a NULL | |
51 | .I host | |
52 | (or | |
53 | .IR serv ) | |
54 | argument or a zero | |
55 | .I hostlen | |
56 | (or | |
57 | .IR servlen ) | |
c13182ef MK |
58 | parameter. |
59 | However, at least one of hostname or service name | |
fea681da MK |
60 | must be requested. |
61 | ||
62 | The | |
63 | .I flags | |
d9bfdb9c | 64 | argument modifies the behavior of |
2777b1ca | 65 | .BR getnameinfo () |
fea681da MK |
66 | as follows: |
67 | .TP | |
68 | .B NI_NOFQDN | |
69 | If set, return only the hostname part of the FQDN for local hosts. | |
70 | .TP | |
71 | .B NI_NUMERICHOST | |
72 | If set, then the numeric form of the hostname is returned. | |
73 | .\" For example, by calling | |
74 | .\" .I inet_ntop() | |
75 | .\" instead of | |
76 | .\" .IR gethostbyaddr() . | |
77 | (When not set, this will still happen in case the node's name | |
78 | cannot be looked up.) | |
79 | .TP | |
80 | .B NI_NAMEREQD | |
81 | If set, then a error is returned if the hostname cannot be looked up. | |
82 | .TP | |
83 | .B NI_NUMERICSERV | |
84 | If set, then the service address is returned in numeric form, | |
85 | for example by its port number. | |
86 | .TP | |
87 | .B NI_DGRAM | |
88 | If set, then the service is datagram (UDP) based rather than | |
c13182ef MK |
89 | stream (TCP) based. |
90 | This is required for the few ports (512-514) | |
fea681da | 91 | that have different services for UDP and TCP. |
22135cad MK |
92 | .SS "Extensions to getaddrinfo() for Internationalized Domain Names" |
93 | .PP | |
94 | Starting with glibc 2.3.4, | |
c13182ef | 95 | .BR getnameinfo () |
22135cad | 96 | has been extended to selectively allow |
c13182ef | 97 | host names to be transparently converted to and from the |
22135cad MK |
98 | Internationalized Domain Name (IDN) format (see RFC 3490, |
99 | .IR "Internationalizing Domain Names in Applications (IDNA)" ). | |
100 | Three new flags are defined: | |
101 | .TP | |
102 | .B NI_IDN | |
103 | If this flag is used, then the name found in the lookup process is | |
c13182ef | 104 | converted from IDN format to the locale's encoding if necessary. |
22135cad MK |
105 | ASCII-only names are not affected by the conversion, which |
106 | makes this flag usable in existing programs and environments. | |
107 | .TP | |
108 | .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES | |
c13182ef | 109 | Setting these flags will enable the |
22135cad | 110 | IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and |
c13182ef MK |
111 | IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 |
112 | conforming host name) | |
22135cad | 113 | flags respectively to be used in the IDNA handling. |
fea681da | 114 | .SH "RETURN VALUE" |
420dad7a | 115 | .\" FIXME glibc defines the following additional errors, some which |
c13182ef | 116 | .\" can probably be returned by getnameinfo(); they need to |
420dad7a | 117 | .\" be documented. |
3d32fee8 MK |
118 | .\" #ifdef __USE_GNU |
119 | .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ | |
120 | .\" #define EAI_CANCELED -101 /* Request canceled. */ | |
121 | .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ | |
122 | .\" #define EAI_ALLDONE -103 /* All requests done. */ | |
123 | .\" #define EAI_INTR -104 /* Interrupted by a signal. */ | |
124 | .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ | |
125 | .\" #endif | |
fea681da | 126 | On success 0 is returned, and node and service names, if requested, |
28d88c17 | 127 | are filled with null-terminated strings, possibly truncated to fit |
fea681da | 128 | the specified buffer lengths. |
3d4d9116 | 129 | On error one of the following non-zero error codes is returned: |
fea681da MK |
130 | .TP |
131 | .B EAI_AGAIN | |
c13182ef MK |
132 | The name could not be resolved at this time. |
133 | Try again later. | |
fea681da MK |
134 | .TP |
135 | .B EAI_BADFLAGS | |
136 | The | |
137 | .I flags | |
138 | parameter has an invalid value. | |
139 | .TP | |
140 | .B EAI_FAIL | |
141 | A non-recoverable error occurred. | |
142 | .TP | |
143 | .B EAI_FAMILY | |
144 | The address family was not recognized, | |
145 | or the address length was invalid for the specified family. | |
146 | .TP | |
147 | .B EAI_MEMORY | |
148 | Out of memory. | |
149 | .TP | |
150 | .B EAI_NONAME | |
151 | The name does not resolve for the supplied parameters. | |
2f0af33b MK |
152 | .B NI_NAMEREQD |
153 | is set and the host's name cannot be located, | |
fea681da MK |
154 | or neither hostname nor service name were requested. |
155 | .TP | |
3d4d9116 MK |
156 | .B EAI_OVERFLOW |
157 | The buffer pointed to by | |
158 | .I host | |
159 | or | |
160 | .I serv | |
161 | was too small. | |
162 | .TP | |
fea681da | 163 | .B EAI_SYSTEM |
c13182ef MK |
164 | A system error occurred. |
165 | The error code can be found in | |
fea681da | 166 | .IR errno . |
6a7f0c48 | 167 | .PP |
d2cf9489 MK |
168 | The |
169 | .BR gai_strerror (3) | |
170 | function translates these error codes to a human readable string, | |
171 | suitable for error reporting. | |
fea681da MK |
172 | .SH FILES |
173 | /etc/hosts | |
174 | .br | |
175 | /etc/nsswitch.conf | |
176 | .br | |
177 | /etc/resolv.conf | |
2b2581ee MK |
178 | .SH "CONFORMING TO" |
179 | RFC\ 2553, POSIX.1-2001. | |
19c98696 | 180 | .SH NOTES |
fea681da MK |
181 | In order to assist the programmer in choosing reasonable sizes |
182 | for the supplied buffers, | |
183 | .I <netdb.h> | |
184 | defines the constants | |
088a639b | 185 | .in +4n |
fea681da | 186 | .nf |
6602f61c | 187 | |
3d32fee8 MK |
188 | #define NI_MAXHOST 1025 |
189 | #define NI_MAXSERV 32 | |
fea681da | 190 | .fi |
6602f61c MK |
191 | .in |
192 | .PP | |
2f0af33b MK |
193 | The former is the constant |
194 | .B MAXDNAME | |
195 | in recent versions of BIND's | |
fea681da | 196 | .I <arpa/nameser.h> |
c13182ef MK |
197 | header file. |
198 | The latter is a guess based on the services listed | |
fea681da | 199 | in the current Assigned Numbers RFC. |
9b336505 | 200 | .SH EXAMPLE |
6602f61c MK |
201 | The following code tries to get the numeric hostname and service name, |
202 | for a given socket address. | |
c13182ef | 203 | Note that there is no hardcoded reference to |
fea681da MK |
204 | a particular address family. |
205 | ||
088a639b | 206 | .in +4n |
fea681da | 207 | .nf |
6602f61c MK |
208 | struct sockaddr *sa; /* input */ |
209 | char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; | |
fea681da | 210 | |
29059a65 | 211 | if (getnameinfo(sa, sa\->sa_len, hbuf, sizeof(hbuf), sbuf, |
6602f61c MK |
212 | sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) |
213 | printf("host=%s, serv=%s\en", hbuf, sbuf); | |
fea681da | 214 | .fi |
6602f61c | 215 | .in |
fea681da MK |
216 | |
217 | The following version checks if the socket address has a | |
218 | reverse address mapping. | |
219 | ||
088a639b | 220 | .in +4n |
6602f61c MK |
221 | .nf |
222 | struct sockaddr *sa; /* input */ | |
223 | char hbuf[NI_MAXHOST]; | |
fea681da | 224 | |
29059a65 | 225 | if (getnameinfo(sa, sa\->sa_len, hbuf, sizeof(hbuf), |
6602f61c MK |
226 | NULL, 0, NI_NAMEREQD)) |
227 | printf("could not resolve hostname"); | |
228 | else | |
229 | printf("host=%s\en", hbuf); | |
fea681da | 230 | .fi |
6602f61c | 231 | .in |
77dbc341 | 232 | .PP |
6602f61c | 233 | An example program using |
77dbc341 MK |
234 | .BR getnameinfo () |
235 | can be found in | |
236 | .BR getaddrinfo (3). | |
fea681da | 237 | .SH "SEE ALSO" |
2f1f4221 | 238 | .BR socket (2), |
fea681da MK |
239 | .BR getaddrinfo (3), |
240 | .BR gethostbyaddr (3), | |
241 | .BR getservbyname (3), | |
242 | .BR getservbyport (3), | |
243 | .BR inet_ntop (3), | |
fea681da MK |
244 | .BR hosts (5), |
245 | .BR services (5), | |
246 | .BR hostname (7), | |
247 | .BR named (8) | |
248 | .LP | |
249 | R. Gilligan, S. Thomson, J. Bound and W. Stevens, | |
250 | .IR "Basic Socket Interface Extensions for IPv6" , | |
331da7c3 | 251 | RFC\ 2553, March 1999. |
fea681da MK |
252 | .LP |
253 | Tatsuya Jinmei and Atsushi Onoe, | |
254 | .IR "An Extension of Format for IPv6 Scoped Addresses" , | |
255 | internet draft, work in progress. | |
29059a65 | 256 | ftp://ftp.ietf.org/internet\-drafts/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt |
fea681da MK |
257 | .LP |
258 | Craig Metz, | |
259 | .IR "Protocol Independence Using the Sockets API" , | |
260 | Proceedings of the freenix track: | |
261 | 2000 USENIX annual technical conference, June 2000. | |
262 | http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html |