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