]>
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 | .\" | |
fea681da MK |
7 | .TH getnameinfo 3 2000-12-11 "Linux Man Page" "UNIX Programmer's Manual" |
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 | |
21 | .BR getnameinfo (3) | |
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 | |
37 | .IR salen | |
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 ) | |
58 | parameter. However, at least one of hostname or service name | |
59 | must be requested. | |
60 | ||
61 | The | |
62 | .I flags | |
63 | argument modifies the behaviour of | |
64 | .BR getnameinfo (3) | |
65 | as follows: | |
66 | .TP | |
67 | .B NI_NOFQDN | |
68 | If set, return only the hostname part of the FQDN for local hosts. | |
69 | .TP | |
70 | .B NI_NUMERICHOST | |
71 | If set, then the numeric form of the hostname is returned. | |
72 | .\" For example, by calling | |
73 | .\" .I inet_ntop() | |
74 | .\" instead of | |
75 | .\" .IR gethostbyaddr() . | |
76 | (When not set, this will still happen in case the node's name | |
77 | cannot be looked up.) | |
78 | .TP | |
79 | .B NI_NAMEREQD | |
80 | If set, then a error is returned if the hostname cannot be looked up. | |
81 | .TP | |
82 | .B NI_NUMERICSERV | |
83 | If set, then the service address is returned in numeric form, | |
84 | for example by its port number. | |
85 | .TP | |
86 | .B NI_DGRAM | |
87 | If set, then the service is datagram (UDP) based rather than | |
88 | stream (TCP) based. This is required for the few ports (512-514) | |
89 | that have different services for UDP and TCP. | |
90 | .SH "RETURN VALUE" | |
91 | On success 0 is returned, and node and service names, if requested, | |
92 | are filled with NUL-terminated strings, possibly truncated to fit | |
93 | the specified buffer lengths. | |
3d4d9116 | 94 | On error one of the following non-zero error codes is returned: |
fea681da MK |
95 | .TP |
96 | .B EAI_AGAIN | |
97 | The name could not be resolved at this time. Try again later. | |
98 | .TP | |
99 | .B EAI_BADFLAGS | |
100 | The | |
101 | .I flags | |
102 | parameter has an invalid value. | |
103 | .TP | |
104 | .B EAI_FAIL | |
105 | A non-recoverable error occurred. | |
106 | .TP | |
107 | .B EAI_FAMILY | |
108 | The address family was not recognized, | |
109 | or the address length was invalid for the specified family. | |
110 | .TP | |
111 | .B EAI_MEMORY | |
112 | Out of memory. | |
113 | .TP | |
114 | .B EAI_NONAME | |
115 | The name does not resolve for the supplied parameters. | |
116 | NI_NAMEREQD is set and the host's name cannot be located, | |
117 | or neither hostname nor service name were requested. | |
118 | .TP | |
3d4d9116 MK |
119 | .B EAI_OVERFLOW |
120 | The buffer pointed to by | |
121 | .I host | |
122 | or | |
123 | .I serv | |
124 | was too small. | |
125 | .TP | |
fea681da MK |
126 | .B EAI_SYSTEM |
127 | A system error occurred. The error code can be found in | |
128 | .IR errno . | |
129 | .SH FILES | |
130 | /etc/hosts | |
131 | .br | |
132 | /etc/nsswitch.conf | |
133 | .br | |
134 | /etc/resolv.conf | |
3d4d9116 MK |
135 | The |
136 | .BR gai_strerror (3) | |
137 | function translates these error codes to a human readable string, | |
138 | suitable for error reporting. | |
fea681da MK |
139 | .SH NOTE |
140 | In order to assist the programmer in choosing reasonable sizes | |
141 | for the supplied buffers, | |
142 | .I <netdb.h> | |
143 | defines the constants | |
144 | .RS | |
145 | .nf | |
146 | # define NI_MAXHOST 1025 | |
147 | .br | |
148 | # define NI_MAXSERV 32 | |
149 | .fi | |
150 | .RE | |
151 | The former is the constant MAXDNAME in recent versions of BIND's | |
152 | .I <arpa/nameser.h> | |
153 | header file. The latter is a guess based on the services listed | |
154 | in the current Assigned Numbers RFC. | |
155 | .SH EXAMPLES | |
156 | The following code tries to get the numeric hostname and service name, for | |
157 | a given socket address. Note that there is no hardcoded reference to | |
158 | a particular address family. | |
159 | ||
160 | .RS | |
161 | .nf | |
162 | struct sockaddr *sa; /* input */ | |
163 | char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; | |
164 | ||
165 | if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, | |
166 | sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) | |
167 | printf("host=%s, serv=%s\en", hbuf, sbuf); | |
168 | .fi | |
169 | .RE | |
170 | ||
171 | The following version checks if the socket address has a | |
172 | reverse address mapping. | |
173 | ||
174 | .RS | |
175 | .fi | |
176 | struct sockaddr *sa; /* input */ | |
177 | char hbuf[NI_MAXHOST]; | |
178 | ||
179 | if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), | |
180 | NULL, 0, NI_NAMEREQD)) | |
181 | printf("could not resolve hostname"); | |
182 | else | |
183 | printf("host=%s\en", hbuf); | |
184 | .fi | |
185 | .RE | |
186 | .SH "CONFORMING TO" | |
187 | RFC 2553. (See also XNS, issue 5.2.) | |
188 | .SH "SEE ALSO" | |
189 | .BR getaddrinfo (3), | |
190 | .BR gethostbyaddr (3), | |
191 | .BR getservbyname (3), | |
192 | .BR getservbyport (3), | |
193 | .BR inet_ntop (3), | |
194 | .BR socket (3), | |
195 | .BR hosts (5), | |
196 | .BR services (5), | |
197 | .BR hostname (7), | |
198 | .BR named (8) | |
199 | .LP | |
200 | R. Gilligan, S. Thomson, J. Bound and W. Stevens, | |
201 | .IR "Basic Socket Interface Extensions for IPv6" , | |
202 | RFC 2553, March 1999. | |
203 | .LP | |
204 | Tatsuya Jinmei and Atsushi Onoe, | |
205 | .IR "An Extension of Format for IPv6 Scoped Addresses" , | |
206 | internet draft, work in progress. | |
207 | ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt | |
208 | .LP | |
209 | Craig Metz, | |
210 | .IR "Protocol Independence Using the Sockets API" , | |
211 | Proceedings of the freenix track: | |
212 | 2000 USENIX annual technical conference, June 2000. | |
213 | http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html |