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