c4d9468ea0
Avoid using parenthesis enclosure macros (.Pq and .Po/.Pc) with plain text. Not only this slows down the mdoc(7) processing significantly, but it also has an undesired (in this case) effect of disabling hyphenation within the entire enclosed block.
312 lines
8.8 KiB
Groff
312 lines
8.8 KiB
Groff
.\" $FreeBSD$
|
|
.\" $KAME: getnameinfo.3,v 1.17 2000/08/09 21:16:17 itojun Exp $
|
|
.\"
|
|
.\" Copyright (c) 1983, 1987, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
|
|
.\"
|
|
.Dd May 25, 1995
|
|
.Dt GETNAMEINFO 3
|
|
.Os
|
|
.\"
|
|
.Sh NAME
|
|
.Nm getnameinfo
|
|
.Nd address-to-nodename translation in protocol-independent manner
|
|
.\"
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <sys/socket.h>
|
|
.Fd #include <netdb.h>
|
|
.Ft int
|
|
.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
|
|
"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
|
|
.\"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn getnameinfo
|
|
function is defined for protocol-independent address-to-nodename translation.
|
|
Its functionality is a reverse conversion of
|
|
.Xr getaddrinfo 3 ,
|
|
and implements similar functionality with
|
|
.Xr gethostbyaddr 3
|
|
and
|
|
.Xr getservbyport 3
|
|
in more sophisticated manner.
|
|
.Pp
|
|
This function looks up an IP address and port number provided by the
|
|
caller in the DNS and system-specific database, and returns text
|
|
strings for both in buffers provided by the caller.
|
|
The function indicates successful completion by a zero return value;
|
|
a non-zero return value indicates failure.
|
|
.Pp
|
|
The first argument,
|
|
.Fa sa ,
|
|
points to either a
|
|
.Li sockaddr_in
|
|
structure (for IPv4) or a
|
|
.Li sockaddr_in6
|
|
structure (for IPv6) that holds the IP address and port number.
|
|
The
|
|
.Fa salen
|
|
argument gives the length of the
|
|
.Li sockaddr_in
|
|
or
|
|
.Li sockaddr_in6
|
|
structure.
|
|
.Pp
|
|
The function returns the nodename associated with the IP address in
|
|
the buffer pointed to by the
|
|
.Fa host
|
|
argument.
|
|
The caller provides the size of this buffer via the
|
|
.Fa hostlen
|
|
argument.
|
|
The service name associated with the port number is returned in the buffer
|
|
pointed to by
|
|
.Fa serv ,
|
|
and the
|
|
.Fa servlen
|
|
argument gives the length of this buffer.
|
|
The caller specifies not to return either string by providing a zero
|
|
value for the
|
|
.Fa hostlen
|
|
or
|
|
.Fa servlen
|
|
arguments.
|
|
Otherwise, the caller must provide buffers large enough to hold the
|
|
nodename and the service name, including the terminating null characters.
|
|
.Pp
|
|
Unfortunately most systems do not provide constants that specify the
|
|
maximum size of either a fully-qualified domain name or a service name.
|
|
Therefore to aid the application in allocating buffers for these two
|
|
returned strings the following constants are defined in
|
|
.Aq Pa netdb.h :
|
|
.Bd -literal -offset
|
|
#define NI_MAXHOST 1025
|
|
#define NI_MAXSERV 32
|
|
.Ed
|
|
.Pp
|
|
The first value is actually defined as the constant
|
|
.Dv MAXDNAME
|
|
in recent versions of BIND's
|
|
.Aq Pa arpa/nameser.h
|
|
header
|
|
(older versions of BIND define this constant to be 256)
|
|
and the second is a guess based on the services listed in the current
|
|
Assigned Numbers RFC.
|
|
.Pp
|
|
The final argument is a
|
|
.Fa flag
|
|
that changes the default actions of this function.
|
|
By default the fully-qualified domain name (FQDN) for the host is
|
|
looked up in the DNS and returned.
|
|
If the flag bit
|
|
.Dv NI_NOFQDN
|
|
is set, only the nodename portion of the FQDN is returned for local hosts.
|
|
.Pp
|
|
If the
|
|
.Fa flag
|
|
bit
|
|
.Dv NI_NUMERICHOST
|
|
is set, or if the host's name cannot be located in the DNS,
|
|
the numeric form of the host's address is returned instead of its name
|
|
(e.g., by calling
|
|
.Fn inet_ntop
|
|
instead of
|
|
.Fn getnodebyaddr ) .
|
|
If the
|
|
.Fa flag
|
|
bit
|
|
.Dv NI_NAMEREQD
|
|
is set, an error is returned if the host's name cannot be located in the DNS.
|
|
.Pp
|
|
If the flag bit
|
|
.Dv NI_NUMERICSERV
|
|
is set, the numeric form of the service address is returned
|
|
(e.g., its port number)
|
|
instead of its name.
|
|
The two
|
|
.Dv NI_NUMERICxxx
|
|
flags are required to support the
|
|
.Fl n
|
|
flag that many commands provide.
|
|
.Pp
|
|
A fifth flag bit,
|
|
.Dv NI_DGRAM ,
|
|
specifies that the service is a datagram service, and causes
|
|
.Fn getservbyport
|
|
to be called with a second argument of
|
|
.Dq udp
|
|
instead of its default of
|
|
.Dq tcp .
|
|
This is required for the few ports (512-514)
|
|
that have different services for UDP and TCP.
|
|
.Pp
|
|
These
|
|
.Dv NI_xxx
|
|
flags are defined in
|
|
.Aq Pa netdb.h .
|
|
.\"
|
|
.Sh EXTENSION
|
|
The implementation allows experimental numeric IPv6 address notation with
|
|
scope identifier.
|
|
IPv6 link-local address will appear as string like
|
|
.Dq Li fe80::1%ne0 ,
|
|
if
|
|
.Dv NI_WITHSCOPEID
|
|
bit is enabled in
|
|
.Ar flags
|
|
argument.
|
|
Refer to
|
|
.Xr getaddrinfo 3
|
|
for the notation.
|
|
.\"
|
|
.Sh EXAMPLES
|
|
The following code tries to get numeric hostname, and service name,
|
|
for given socket address.
|
|
Observe that there is no hardcoded reference to particular address family.
|
|
.Bd -literal -offset indent
|
|
struct sockaddr *sa; /* input */
|
|
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
|
|
|
|
if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
|
|
sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
|
|
errx(1, "could not get numeric hostname");
|
|
/*NOTREACHED*/
|
|
}
|
|
printf("host=%s, serv=%s\\n", hbuf, sbuf);
|
|
.Ed
|
|
.Pp
|
|
The following version checks if the socket address has reverse address mapping.
|
|
.Bd -literal -offset indent
|
|
struct sockaddr *sa; /* input */
|
|
char hbuf[NI_MAXHOST];
|
|
|
|
if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
|
|
NI_NAMEREQD)) {
|
|
errx(1, "could not resolve hostname");
|
|
/*NOTREACHED*/
|
|
}
|
|
printf("host=%s\\n", hbuf);
|
|
.Ed
|
|
.\"
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/nsswitch.conf -compact
|
|
.It Pa /etc/hosts
|
|
.It Pa /etc/nsswitch.conf
|
|
.It Pa /etc/resolv.conf
|
|
.El
|
|
.\"
|
|
.Sh DIAGNOSTICS
|
|
The function indicates successful completion by a zero return value;
|
|
a non-zero return value indicates failure.
|
|
Error codes are as below:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EAI_AGAIN
|
|
The name could not be resolved at this time.
|
|
Future attempts may succeed.
|
|
.It Bq Er EAI_BADFLAGS
|
|
The flags had an invalid value.
|
|
.It Bq Er EAI_FAIL
|
|
A non-recoverable error occurred.
|
|
.It Bq Er EAI_FAMILY
|
|
The address family was not recognized or the address length was invalid
|
|
for the specified family.
|
|
.It Bq Er EAI_MEMORY
|
|
There was a memory allocation failure.
|
|
.It Bq Er EAI_NONAME
|
|
The name does not resolve for the supplied parameters.
|
|
.Dv NI_NAMEREQD
|
|
is set and the host's name cannot be located,
|
|
or both nodename and servname were null.
|
|
.It Bq Er EAI_SYSTEM
|
|
A system error occurred.
|
|
The error code can be found in errno.
|
|
.El
|
|
.\"
|
|
.Sh SEE ALSO
|
|
.Xr getaddrinfo 3 ,
|
|
.Xr gethostbyaddr 3 ,
|
|
.Xr getservbyport 3 ,
|
|
.Xr hosts 5 ,
|
|
.Xr services 5 ,
|
|
.Xr hostname 7 ,
|
|
.Xr named 8
|
|
.Pp
|
|
.Rs
|
|
.%A R. Gilligan
|
|
.%A S. Thomson
|
|
.%A J. Bound
|
|
.%A W. Stevens
|
|
.%T Basic Socket Interface Extensions for IPv6
|
|
.%R RFC2553
|
|
.%D March 1999
|
|
.Re
|
|
.Rs
|
|
.%A Tatsuya Jinmei
|
|
.%A Atsushi Onoe
|
|
.%T "An Extension of Format for IPv6 Scoped Addresses"
|
|
.%R internet draft
|
|
.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
|
|
.%O work in progress material
|
|
.Re
|
|
.Rs
|
|
.%A Craig Metz
|
|
.%T Protocol Independence Using the Sockets API
|
|
.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
|
|
.%D June 2000
|
|
.Re
|
|
.\"
|
|
.Sh HISTORY
|
|
The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
|
|
.\"
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn getaddrinfo
|
|
function is defined in
|
|
.St -p1003.1g-2000 ,
|
|
and documented in
|
|
.Dq Basic Socket Interface Extensions for IPv6
|
|
(RFC2553).
|
|
.\"
|
|
.Sh BUGS
|
|
The current implementation is not thread-safe.
|
|
.Pp
|
|
The text was shamelessly copied from RFC2553.
|
|
.Pp
|
|
The type of the 2nd argument should be
|
|
.Li socklen_t
|
|
for RFC2553 conformance.
|
|
The current code is based on pre-RFC2553 specification.
|