lookup.subproj/getnameinfo.3

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