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