man3/getnameinfo.3

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