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