lib/libc/net/getnameinfo.3

   1 .\" Copyright (c) 1983, 1987, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  33 .\"     $Id: getnameinfo.3,v 1.2 1999/10/07 04:46:27 itojun Exp $
  34 .\"     $FreeBSD$
  35 .\"
  36 .Dd May 25, 1995
  37 .Dt GETNAMEINFO 3
  38 .Os KAME
  39 .\"
  40 .Sh NAME
  41 .Nm getnameinfo
  42 .Nd address-to-nodename translation in protocol-independent manner
  43 .\"
  44 .Sh SYNOPSIS
  45 .Fd #include <sys/types.h>
  46 .Fd #include <sys/socket.h>
  47 .Fd #include <netdb.h>
  48 .Ft int
  49 .Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
  50 .\"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn getnameinfo
  54 function is defined for protocol-independent address-to-nodename translation.
  55 Its functionality is a reverse conversion of
  56 .Xr getaddrinfo 3 ,
  57 and implements similar functionality with
  58 .Xr gethostbyaddr 3 and
  59 .Xr getservbyport 3
  60 in more sophisticated manner.
  61 .Pp
  62 This function looks up an IP address and port number provided by the
  63 caller in the DNS and system-specific database, and returns text
  64 strings for both in buffers provided by the caller.
  65 The function indicates successful completion by a zero return value;
  66 a non-zero return value indicates failure.
  67 .Pp
  68 The first argument,
  69 .Fa sa ,
  70 points to either a
  71 .Fa sockaddr_in
  72 structure (for IPv4) or a
  73 .Fa sockaddr_in6
  74 structure (for IPv6) that holds the IP address and port number.
  75 The
  76 .Fa salen
  77 argument gives the length of the
  78 .Fa sockaddr_in
  79 or
  80 .Fa sockaddr_in6
  81 structure.
  82 .Pp
  83 The function returns the nodename associated with the IP address in
  84 the buffer pointed to by the
  85 .Fa host
  86 argument.
  87 The caller provides the size of this buffer via the
  88 .Fa hostlen
  89 argument.
  90 The service name associated with the port number is returned in the buffer
  91 pointed to by
  92 .Fa serv ,
  93 and the
  94 .Fa servlen
  95 argument gives the length of this buffer.
  96 The caller specifies not to return either string by providing a zero
  97 value for the
  98 .Fa hostlen
  99 or
 100 .Fa servlen
 101 arguments.
 102 Otherwise, the caller must provide buffers large enough to hold the
 103 nodename and the  service name, including the terminating null characters.
 104 .Pp
 105 Unfortunately most systems do not provide constants that specify the
 106 maximum size of either a fully-qualified domain name or a service name.
 107 Therefore to aid the application in allocating buffers for these two
 108 returned strings the following constants are defined in
 109 .Li <netdb.h> :
 110 .Bd -literal -offset
 111 #define NI_MAXHOST  1025
 112 #define NI_MAXSERV    32
 113 .Ed
 114 .Pp
 115 The first value is actually defined as the constant
 116 .Dv MAXDNAME
 117 in recent versions of BIND's
 118 .Li <arpa/nameser.h>
 119 header
 120 .Po
 121 older versions of BIND define this constant to be 256
 122 .Pc
 123 and the second is a guess based on the services listed in the current
 124 Assigned Numbers RFC.
 125 .Pp
 126 The final argument is a
 127 .Fa flag
 128 that changes the default actions of this function.
 129 By default the fully-qualified domain name (FQDN) for the host is
 130 looked up in the DNS and returned.
 131 If the flag bit
 132 .Dv NI_NOFQDN
 133 is set, only the nodename portion of the FQDN is returned for local hosts.
 134 .Pp
 135 If the
 136 .Fa flag
 137 bit
 138 .Dv NI_NUMERICHOST
 139 is set, or if the host's name cannot be located in the DNS,
 140 the numeric form of the host's address is returned instead of its name
 141 .Po
 142 e.g., by calling
 143 .Fn inet_ntop
 144 instead of
 145 .Fn getnodebyaddr
 146 .Pc .
 147 If the
 148 .Fa flag
 149 bit
 150 .Dv NI_NAMEREQD
 151 is set, an error is returned if the host's name cannot be located in the DNS.
 152 .Pp
 153 If the flag bit
 154 .Dv NI_NUMERICSERV
 155 is set, the numeric form of the service address is returned
 156 .Pq e.g., its port number
 157 instead of its name.
 158 The two
 159 .Dv NI_NUMERICxxx
 160 flags are required to support the
 161 .Li "-n"
 162 flag that many commands provide.
 163 .Pp
 164 A fifth flag bit,
 165 .Dv NI_DGRAM ,
 166 specifies that the service is a datagram service, and causes
 167 .Fn getservbyport
 168 to be called with a second argument of "udp" instead of its default of "tcp".
 169 This is required for the few ports (512-514)
 170 that have different services for UDP and TCP.
 171 .Pp
 172 These
 173 .Dv NI_xxx
 174 flags are defined in
 175 .Li <netdb.h> .
 176 .\"
 177 .Sh EXTENSION
 178 The implementation allows experimental numeric IPv6 address notation with
 179 scope identifier.
 180 IPv6 link-local address will appear as string like
 181 .Dq Li fe80::1@ne0 ,
 182 if
 183 .Dv NI_WITHSCOPEID
 184 bit is enabled in
 185 .Ar flags
 186 argument.
 187 Refer to
 188 .Xr getaddrinfo 3
 189 for the notation.
 190 .\"
 191 .Sh FILES
 192 .Bl -tag -width /etc/resolv.conf -compact
 193 .It Pa /etc/hosts
 194 .It Pa /etc/host.conf
 195 .It Pa /etc/resolv.conf
 196 .El
 197 .\"
 198 .Sh DIAGNOSTICS
 199 The function indicates successful completion by a zero return value;
 200 a non-zero return value indicates failure.
 201 .\"
 202 .Sh SEE ALSO
 203 .Xr getaddrinfo 3 ,
 204 .Xr gethostbyaddr 3 ,
 205 .Xr getservbyport 3 ,
 206 .Xr hosts 5 ,
 207 .Xr services 5 ,
 208 .Xr hostname 7 ,
 209 .Xr named 8
 210 .Pp
 211 .Rs
 212 .%A R. Gilligan
 213 .%A S. Thomson
 214 .%A J. Bound
 215 .%A W. Stevens
 216 .%T Basic Socket Interface Extensions for IPv6
 217 .%R RFC2553
 218 .%D March 1999
 219 .Re
 220 .\"
 221 .Sh HISTORY
 222 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 223 .\"
 224 .Sh STANDARDS
 225 The
 226 .Fn getaddrinfo
 227 function is defined IEEE POSIX 1003.1g draft specification,
 228 and documented in ``Basic Socket Interface Extensions for IPv6''
 229 .Pq RFC2533 .
 230 .\"
 231 .Sh BUGS
 232 The text was shamelessly copied from RFC2553.