original/man3/getnameinfo.3

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