1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="TCP/IP Library Reference"
23 HREF="tcpip-library-reference.html"><LINK
26 HREF="net-common-tcpip-manpages-getifaddrs.html"><LINK
29 HREF="net-common-tcpip-manpages-getnetent.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="net-common-tcpip-manpages-getifaddrs.html"
65 >Chapter 38. TCP/IP Library Reference</TD
71 HREF="net-common-tcpip-manpages-getnetent.html"
85 NAME="NET-COMMON-TCPIP-MANPAGES-GETNAMEINFO">getnameinfo</H1
94 >GETNAMEINFO(3) System Library Functions Manual GETNAMEINFO(3)
97 getnameinfo - address-to-nodename translation in protocol-independent
101 #include <sys/types.h>
102 #include <sys/socket.h>
103 #include <netdb.h>
106 getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host,
107 size_t hostlen, char *serv, size_t servlen, int flags);
110 The getnameinfo() function is defined for protocol-independent address-
111 to-nodename translation. Its functionality is a reverse conversion of
112 getaddrinfo(3), and implements similar functionality with
113 gethostbyaddr(3) and getservbyport(3) in more sophisticated manner.
115 This function looks up an IP address and port number provided by the
116 caller in the DNS and system-specific database, and returns text strings
117 for both in buffers provided by the caller. The function indicates suc-
118 cessful completion by a zero return value; a non-zero return value indi-
121 The first argument, sa, points to either a sockaddr_in structure (for
122 IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address
123 and port number. The salen argument gives the length of the sockaddr_in
124 or sockaddr_in6 structure.
126 The function returns the nodename associated with the IP address in the
127 buffer pointed to by the host argument. The caller provides the size of
128 this buffer via the hostlen argument. The service name associated with
129 the port number is returned in the buffer pointed to by serv, and the
130 servlen argument gives the length of this buffer. The caller specifies
131 not to return either string by providing a zero value for the hostlen or
132 servlen arguments. Otherwise, the caller must provide buffers large
133 enough to hold the nodename and the service name, including the terminat-
136 Unfortunately most systems do not provide constants that specify the max-
137 imum size of either a fully-qualified domain name or a service name.
138 Therefore to aid the application in allocating buffers for these two
139 returned strings the following constants are defined in <netdb.h>:
141 #define NI_MAXHOST MAXHOSTNAMELEN
142 #define NI_MAXSERV 32
144 The first value is actually defined as the constant MAXDNAME in recent
145 versions of BIND's <arpa/nameser.h> header (older versions of BIND define
146 this constant to be 256) and the second is a guess based on the services
147 listed in the current Assigned Numbers RFC.
149 The final argument is a flag that changes the default actions of this
150 function. By default the fully-qualified domain name (FQDN) for the host
151 is looked up in the DNS and returned. If the flag bit NI_NOFQDN is set,
152 only the nodename portion of the FQDN is returned for local hosts.
154 If the flag bit NI_NUMERICHOST is set, or if the host's name cannot be
155 located in the DNS, the numeric form of the host's address is returned
156 instead of its name (e.g., by calling inet_ntop() instead of
157 gethostbyaddr()). If the flag bit NI_NAMEREQD is set, an error is
158 returned if the host's name cannot be located in the DNS.
160 If the flag bit NI_NUMERICSERV is set, the numeric form of the service
161 address is returned (e.g., its port number) instead of its name. The two
162 NI_NUMERICxxx flags are required to support the -n flag that many com-
165 A fifth flag bit, NI_DGRAM, specifies that the service is a datagram ser-
166 vice, and causes getservbyport() to be called with a second argument of
167 "udp" instead of its default of "tcp". This is required for the few
168 ports (512-514) that have different services for UDP and TCP.
170 These NI_xxx flags are defined in <netdb.h>.
172 Extension for scoped IPv6 address
173 The implementation allows experimental numeric IPv6 address notation with
174 scope identifier. IPv6 link-local address will appear as string like
175 ``fe80::1%ne0'', if NI_WITHSCOPEID bit is enabled in flags argument.
176 Refer to getaddrinfo(3) for the notation.
179 The following code tries to get numeric hostname, and service name, for
180 given socket address. Observe that there is no hardcoded reference to
181 particular address family.
183 struct sockaddr *sa; /* input */
184 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
186 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
187 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
188 errx(1, "could not get numeric hostname");
191 printf("host=%s, serv=%s\n", hbuf, sbuf);
193 The following version checks if the socket address has reverse address
196 struct sockaddr *sa; /* input */
197 char hbuf[NI_MAXHOST];
199 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
201 errx(1, "could not resolve hostname");
204 printf("host=%s\n", hbuf);
207 The function indicates successful completion by a zero return value; a
208 non-zero return value indicates failure. Error codes are as below:
210 EAI_AGAIN The name could not be resolved at this time. Future
211 attempts may succeed.
213 EAI_BADFLAGS The flags had an invalid value.
215 EAI_FAIL A non-recoverable error occurred.
217 EAI_FAMILY The address family was not recognized or the address
218 length was invalid for the specified family.
220 EAI_MEMORY There was a memory allocation failure.
222 EAI_NONAME The name does not resolve for the supplied parameters.
223 NI_NAMEREQD is set and the host's name cannot be
224 located, or both nodename and servname were null.
226 EAI_SYSTEM A system error occurred. The error code can be found
230 getaddrinfo(3), gethostbyaddr(3), getservbyport(3), hosts(5),
231 resolv.conf(5), services(5), hostname(7), named(8)
233 R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
234 Extensions for IPv6, RFC2553, March 1999.
236 Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
237 Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
238 work in progress material.
240 Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
241 the freenix track: 2000 USENIX annual technical conference, June 2000.
244 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
248 The getaddrinfo() function is defined IEEE POSIX 1003.1g draft specifica-
249 tion, and documented in ``Basic Socket Interface Extensions for IPv6''
253 The current implementation is not thread-safe.
255 The text was shamelessly copied from RFC2553.
257 OpenBSD intentionally uses different NI_MAXHOST value from what RFC2553
258 suggests, to avoid buffer length handling mistakes.
271 SUMMARY="Footer navigation table"
282 HREF="net-common-tcpip-manpages-getifaddrs.html"
300 HREF="net-common-tcpip-manpages-getnetent.html"
316 HREF="tcpip-library-reference.html"