lib/libcr/net/getnameinfo.3

   1 .\"     $FreeBSD: src/lib/libc/net/getnameinfo.3,v 1.2.2.8 2001/12/14 18:33:55 ru Exp $
   2 .\"     $DragonFly: src/lib/libcr/net/Attic/getnameinfo.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
   3 .\"     $KAME: getnameinfo.3,v 1.17 2000/08/09 21:16:17 itojun Exp $
   4 .\"
   5 .\" Copyright (c) 1983, 1987, 1991, 1993
   6 .\"     The Regents of the University of California.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  37 .\"
  38 .Dd May 25, 1995
  39 .Dt GETNAMEINFO 3
  40 .Os
  41 .\"
  42 .Sh NAME
  43 .Nm getnameinfo
  44 .Nd address-to-nodename translation in protocol-independent manner
  45 .\"
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In sys/types.h
  50 .In sys/socket.h
  51 .In netdb.h
  52 .Ft int
  53 .Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
  54 "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
  55 .\"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn getnameinfo
  59 function is defined for protocol-independent address-to-nodename translation.
  60 Its functionality is a reverse conversion of
  61 .Xr getaddrinfo 3 ,
  62 and implements similar functionality with
  63 .Xr gethostbyaddr 3
  64 and
  65 .Xr getservbyport 3
  66 in more sophisticated manner.
  67 .Pp
  68 This function looks up an IP address and port number provided by the
  69 caller in the DNS and system-specific database, and returns text
  70 strings for both in buffers provided by the caller.
  71 The function indicates successful completion by a zero return value;
  72 a non-zero return value indicates failure.
  73 .Pp
  74 The first argument,
  75 .Fa sa ,
  76 points to either a
  77 .Li sockaddr_in
  78 structure (for IPv4) or a
  79 .Li sockaddr_in6
  80 structure (for IPv6) that holds the IP address and port number.
  81 The
  82 .Fa salen
  83 argument gives the length of the
  84 .Li sockaddr_in
  85 or
  86 .Li sockaddr_in6
  87 structure.
  88 .Pp
  89 The function returns the nodename associated with the IP address in
  90 the buffer pointed to by the
  91 .Fa host
  92 argument.
  93 The caller provides the size of this buffer via the
  94 .Fa hostlen
  95 argument.
  96 The service name associated with the port number is returned in the buffer
  97 pointed to by
  98 .Fa serv ,
  99 and the
 100 .Fa servlen
 101 argument gives the length of this buffer.
 102 The caller specifies not to return either string by providing a zero
 103 value for the
 104 .Fa hostlen
 105 or
 106 .Fa servlen
 107 arguments.
 108 Otherwise, the caller must provide buffers large enough to hold the
 109 nodename and the service name, including the terminating null characters.
 110 .Pp
 111 Unfortunately most systems do not provide constants that specify the
 112 maximum size of either a fully-qualified domain name or a service name.
 113 Therefore to aid the application in allocating buffers for these two
 114 returned strings the following constants are defined in
 115 .Aq Pa netdb.h :
 116 .Bd -literal -offset
 117 #define NI_MAXHOST  1025
 118 #define NI_MAXSERV    32
 119 .Ed
 120 .Pp
 121 The first value is actually defined as the constant
 122 .Dv MAXDNAME
 123 in recent versions of BIND's
 124 .Aq Pa arpa/nameser.h
 125 header
 126 (older versions of BIND define this constant to be 256)
 127 and the second is a guess based on the services listed in the current
 128 Assigned Numbers RFC.
 129 .Pp
 130 The final argument is a
 131 .Fa flag
 132 that changes the default actions of this function.
 133 By default the fully-qualified domain name (FQDN) for the host is
 134 looked up in the DNS and returned.
 135 If the flag bit
 136 .Dv NI_NOFQDN
 137 is set, only the nodename portion of the FQDN is returned for local hosts.
 138 .Pp
 139 If the
 140 .Fa flag
 141 bit
 142 .Dv NI_NUMERICHOST
 143 is set, or if the host's name cannot be located in the DNS,
 144 the numeric form of the host's address is returned instead of its name
 145 (e.g., by calling
 146 .Fn inet_ntop
 147 instead of
 148 .Fn getnodebyaddr ) .
 149 If the
 150 .Fa flag
 151 bit
 152 .Dv NI_NAMEREQD
 153 is set, an error is returned if the host's name cannot be located in the DNS.
 154 .Pp
 155 If the flag bit
 156 .Dv NI_NUMERICSERV
 157 is set, the numeric form of the service address is returned
 158 (e.g., its port number)
 159 instead of its name.
 160 The two
 161 .Dv NI_NUMERICxxx
 162 flags are required to support the
 163 .Fl n
 164 flag that many commands provide.
 165 .Pp
 166 A fifth flag bit,
 167 .Dv NI_DGRAM ,
 168 specifies that the service is a datagram service, and causes
 169 .Fn getservbyport
 170 to be called with a second argument of
 171 .Dq udp
 172 instead of its default of
 173 .Dq tcp .
 174 This is required for the few ports (512-514)
 175 that have different services for UDP and TCP.
 176 .Pp
 177 These
 178 .Dv NI_xxx
 179 flags are defined in
 180 .Aq Pa netdb.h .
 181 .\"
 182 .Sh EXTENSION
 183 The implementation allows experimental numeric IPv6 address notation with
 184 scope identifier.
 185 IPv6 link-local address will appear as string like
 186 .Dq Li fe80::1%ne0 ,
 187 if
 188 .Dv NI_WITHSCOPEID
 189 bit is enabled in
 190 .Ar flags
 191 argument.
 192 Refer to
 193 .Xr getaddrinfo 3
 194 for the notation.
 195 .\"
 196 .Sh EXAMPLES
 197 The following code tries to get numeric hostname, and service name,
 198 for given socket address.
 199 Observe that there is no hardcoded reference to particular address family.
 200 .Bd -literal -offset indent
 201 struct sockaddr *sa;    /* input */
 202 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
 203
 204 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
 205     sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
 206         errx(1, "could not get numeric hostname");
 207         /*NOTREACHED*/
 208 }
 209 printf("host=%s, serv=%s\\n", hbuf, sbuf);
 210 .Ed
 211 .Pp
 212 The following version checks if the socket address has reverse address mapping.
 213 .Bd -literal -offset indent
 214 struct sockaddr *sa;    /* input */
 215 char hbuf[NI_MAXHOST];
 216
 217 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
 218     NI_NAMEREQD)) {
 219         errx(1, "could not resolve hostname");
 220         /*NOTREACHED*/
 221 }
 222 printf("host=%s\\n", hbuf);
 223 .Ed
 224 .\"
 225 .Sh FILES
 226 .Bl -tag -width /etc/resolv.conf -compact
 227 .It Pa /etc/hosts
 228 .It Pa /etc/host.conf
 229 .It Pa /etc/resolv.conf
 230 .El
 231 .\"
 232 .Sh DIAGNOSTICS
 233 The function indicates successful completion by a zero return value;
 234 a non-zero return value indicates failure.
 235 Error codes are as below:
 236 .Bl -tag -width Er
 237 .It Bq Er EAI_AGAIN
 238 The name could not be resolved at this time.
 239 Future attempts may succeed.
 240 .It Bq Er EAI_BADFLAGS
 241 The flags had an invalid value.
 242 .It Bq Er EAI_FAIL
 243 A non-recoverable error occurred.
 244 .It Bq Er EAI_FAMILY
 245 The address family was not recognized or the address length was invalid
 246 for the specified family.
 247 .It Bq Er EAI_MEMORY
 248 There was a memory allocation failure.
 249 .It Bq Er EAI_NONAME
 250 The name does not resolve for the supplied parameters.
 251 .Dv NI_NAMEREQD
 252 is set and the host's name cannot be located,
 253 or both nodename and servname were null.
 254 .It Bq Er EAI_SYSTEM
 255 A system error occurred.
 256 The error code can be found in errno.
 257 .El
 258 .\"
 259 .Sh SEE ALSO
 260 .Xr getaddrinfo 3 ,
 261 .Xr gethostbyaddr 3 ,
 262 .Xr getservbyport 3 ,
 263 .Xr hosts 5 ,
 264 .Xr services 5 ,
 265 .Xr hostname 7 ,
 266 .Xr named 8
 267 .Pp
 268 .Rs
 269 .%A R. Gilligan
 270 .%A S. Thomson
 271 .%A J. Bound
 272 .%A W. Stevens
 273 .%T Basic Socket Interface Extensions for IPv6
 274 .%R RFC2553
 275 .%D March 1999
 276 .Re
 277 .Rs
 278 .%A Tatsuya Jinmei
 279 .%A Atsushi Onoe
 280 .%T "An Extension of Format for IPv6 Scoped Addresses"
 281 .%R internet draft
 282 .%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 283 .%O work in progress material
 284 .Re
 285 .Rs
 286 .%A Craig Metz
 287 .%T Protocol Independence Using the Sockets API
 288 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 289 .%D June 2000
 290 .Re
 291 .\"
 292 .Sh HISTORY
 293 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 294 .\"
 295 .Sh STANDARDS
 296 The
 297 .Fn getaddrinfo
 298 function is defined in
 299 .St -p1003.1g-2000 ,
 300 and documented in
 301 .Dq Basic Socket Interface Extensions for IPv6
 302 (RFC2553).
 303 .\"
 304 .Sh BUGS
 305 The current implementation is not thread-safe.
 306 .Pp
 307 The text was shamelessly copied from RFC2553.
 308 .Pp
 309 The type of the 2nd argument should be
 310 .Li socklen_t
 311 for RFC2553 conformance.
 312 The current code is based on pre-RFC2553 specification.