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