summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoritojun <itojun@NetBSD.org>2005-01-11 07:26:57 +0000
committeritojun <itojun@NetBSD.org>2005-01-11 07:26:57 +0000
commitf6b6f2cd66ac2bcd67d53ef236b2cb4d5272da2d (patch)
treed439dd16a24de03df7a6e55ab312b937f97725a9
parent554ce4f360b2d4f53e6c2ee6def6d7bfa89ff60f (diff)
written-from-scratch manpage (fixes ISOC copyright violation)
-rw-r--r--lib/libc/net/gai_strerror.394
-rw-r--r--lib/libc/net/getnameinfo.3352
2 files changed, 231 insertions, 215 deletions
diff --git a/lib/libc/net/gai_strerror.3 b/lib/libc/net/gai_strerror.3
new file mode 100644
index 00000000000..d21abf1d255
--- /dev/null
+++ b/lib/libc/net/gai_strerror.3
@@ -0,0 +1,94 @@
+.\" $NetBSD: gai_strerror.3,v 1.1 2005/01/11 07:26:57 itojun Exp $
+.\" $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun Exp $
+.\" $OpenBSD: gai_strerror.3,v 1.4 2004/12/20 23:04:53 millert Exp $
+.\"
+.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (C) 2000, 2001 Internet Software Consortium.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
+.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd December 20, 2004
+.Dt GAI_STRERROR 3
+.Os
+.Sh NAME
+.Nm gai_strerror
+.Nd get error message string from EAI_xxx error code
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Fd #include <netdb.h>
+.Ft "const char *"
+.Fn gai_strerror "int ecode"
+.Sh DESCRIPTION
+The
+.Fn gai_strerror
+function returns an error message string corresponding to the error code
+returned by
+.Xr getaddrinfo 3
+or
+.Xr getnameinfo 3 .
+.Pp
+The following error codes and their meaning are defined in
+.Aq Pa netdb.h :
+.Pp
+.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact
+.It Dv EAI_ADDRFAMILY
+address family for
+.Fa hostname
+not supported
+.It Dv EAI_AGAIN
+temporary failure in name resolution
+.It Dv EAI_BADFLAGS
+invalid value for
+.Fa ai_flags
+.It Dv EAI_BADHINTS
+invalid value for
+.Fa hints
+.It Dv EAI_FAIL
+non-recoverable failure in name resolution
+.It Dv EAI_FAMILY
+.Fa ai_family
+not supported.
+.It Dv EAI_MEMORY
+memory allocation failure
+.It Dv EAI_NODATA
+no address associated with
+.Fa hostname
+.It Dv EAI_NONAME
+.Fa hostname
+or
+.Fa servname
+not provided, or not known
+.It Dv EAI_PROTOCOL
+resolved protocol is unknown
+.It Dv EAI_SERVICE
+.Fa servname
+not supported for
+.Fa ai_socktype
+.It Dv EAI_SOCKTYPE
+.Fa ai_socktype
+not supported
+.It Dv EAI_SYSTEM
+system error returned in
+.Va errno
+.El
+.Sh RETURN VALUES
+.Fn gai_strerror
+returns a pointer to the error message string corresponding to
+.Fa ecode .
+If
+.Fa ecode
+is out of range, an implementation-specific error message string is returned.
+.Sh SEE ALSO
+.Xr getaddrinfo 3 ,
+.Xr getnameinfo 3
diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3
index 9a466e3a6ad..a9cb64a9100 100644
--- a/lib/libc/net/getnameinfo.3
+++ b/lib/libc/net/getnameinfo.3
@@ -1,258 +1,174 @@
-.\" $NetBSD: getnameinfo.3,v 1.32 2004/12/20 18:30:26 christos Exp $
-.\" $KAME: getnameinfo.3,v 1.27 2003/04/30 06:06:42 itojun Exp $
+.\" $NetBSD: getnameinfo.3,v 1.33 2005/01/11 07:26:57 itojun Exp $
+.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $
+.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $
.\"
-.\" Copyright (c) 1983, 1987, 1991, 1993
-.\" The Regents of the University of California. All rights reserved.
+.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (C) 2000, 2001 Internet Software Consortium.
.\"
-.\" 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. 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.
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
.\"
-.\" 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.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
+.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
.\"
-.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
-.\"
-.Dd August 28, 2003
+.Dd December 20, 2004
.Dt GETNAMEINFO 3
.Os
-.\"
.Sh NAME
.Nm getnameinfo
-.Nd address-to-nodename translation in protocol-independent manner
-.\"
-.Sh LIBRARY
-.Lb libc
-.\"
+.Nd socket address structure to hostname and service name
.Sh SYNOPSIS
-.In netdb.h
+.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" "socklen_t hostlen" "char *serv" "socklen_t servlen" \
-"int flags"
-.\"
+.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 to
+function is used to convert a
+.Li sockaddr
+structure to a pair of host name and service strings.
+It is a replacement for and provides more flexibility than the
.Xr gethostbyaddr 3
and
.Xr getservbyport 3
-in a 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.
+functions and is the converse of the
+.Xr getaddrinfo 3
+function.
.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
+structure
+.Fa sa
+should point to either a
.Li sockaddr_in
or
.Li sockaddr_in6
-structure.
+structure (for IPv4 or IPv6 respectively) that is
+.Fa salen
+bytes long.
.Pp
-The function returns the nodename associated with the IP address in
-the buffer pointed to by the
+The host and service names associated with
+.Fa sa
+are stored in
.Fa host
-argument.
-The caller provides the size of this buffer via the
+and
+.Fa serv
+which have length parameters
.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
+and
+.Fa servlen .
+The maximum value for
.Fa hostlen
-or
+is
+.Dv NI_MAXHOST
+and
+the maximum value for
.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
-.Po
-older versions of BIND define this constant to be 256
-.Pc
-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
-.Po
-e.g., by calling
-.Fn inet_ntop
-instead of
-.Fn gethostbyaddr
-.Pc .
-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
-.Pq 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.
+is
+.Dv NI_MAXSERV ,
+as defined by
+.Aq Pa netdb.h .
+If a length parameter is zero, no string will be stored.
+Otherwise, enough space must be provided to store the
+host name or service string plus a byte for the NUL terminator.
.Pp
-A fifth flag bit,
-.Dv NI_DGRAM ,
-specifies that the service is a datagram service, and causes
-.Fn getservbyport
+The
+.Fa flags
+argument is formed by
+.Tn OR Ns 'ing
+the following values:
+.Bl -tag -width "NI_NUMERICHOSTXX"
+.It Dv NI_NOFQDN
+A fully qualified domain name is not required for local hosts.
+The local part of the fully qualified domain name is returned instead.
+.It Dv NI_NUMERICHOST
+Return the address in numeric form, as if calling
+.Xr inet_ntop 3 ,
+instead of a host name.
+.It Dv NI_NAMEREQD
+A name is required.
+If the host name cannot be found in DNS and this flag is set,
+a non-zero error code is returned.
+If the host name is not found and the flag is not set, the
+address is returned in numeric form.
+.It NI_NUMERICSERV
+The service name is returned as a digit string representing the port number.
+.It NI_DGRAM
+Specifies that the service being looked up is a datagram
+service, and causes
+.Xr getservbyport 3
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.
+This is required for the few ports (512\-514) that have different services
+for
+.Tn UDP
+and
+.Tn TCP .
+.El
.Pp
-These
-.Dv NI_xxx
-flags are defined in
-.Aq Pa netdb.h .
-.\"
-.Ss Extension for scoped IPv6 address
-The implementation allows experimental numeric IPv6 address notation with
-scope identifier.
+This implementation allows numeric IPv6 address notation with scope identifier,
+as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
IPv6 link-local address will appear as a string like
.Dq Li fe80::1%ne0 .
Refer to
.Xr getaddrinfo 3
-for the notation.
-.\"
+for more information.
+.Sh RETURN VALUES
+.Fn getnameinfo
+returns zero on success or one of the error codes listed in
+.Xr gai_strerror 3
+if an error occurs.
.Sh EXAMPLES
-The following code tries to get a numeric hostname, and service name,
-for given socket address.
+The following code tries to get a numeric host name, and service name,
+for a given socket address.
Observe that there is no hardcoded reference to a particular address family.
.Bd -literal -offset indent
struct sockaddr *sa; /* input */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
-if (getnameinfo(sa, sa-\*[Gt]sa_len, hbuf, sizeof(hbuf), sbuf,
+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);
+printf("host=%s, serv=%s\en", hbuf, sbuf);
.Ed
.Pp
-The following version checks if the socket address has reverse address mapping.
+The following version checks if the socket address has a reverse address mapping:
.Bd -literal -offset indent
struct sockaddr *sa; /* input */
char hbuf[NI_MAXHOST];
-if (getnameinfo(sa, sa-\*[Gt]sa_len, hbuf, sizeof(hbuf), NULL, 0,
+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);
+printf("host=%s\en", hbuf);
.Ed
-.\"
-.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 Dv EAI_AGAIN
-The name could not be resolved at this time.
-Future attempts may succeed.
-.It Dv EAI_BADFLAGS
-The flags had an invalid value.
-.It Dv EAI_FAIL
-A non-recoverable error occurred.
-.It Dv EAI_FAMILY
-The address family was not recognized or the address length was invalid
-for the specified family.
-.It Dv EAI_MEMORY
-There was a memory allocation failure.
-.It Dv 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 Dv EAI_SYSTEM
-A system error occurred.
-The error code can be found in errno.
-.El
-.\"
.Sh SEE ALSO
+.Xr gai_strerror 3 ,
.Xr getaddrinfo 3 ,
.Xr gethostbyaddr 3 ,
.Xr getservbyport 3 ,
+.Xr inet_ntop 3 ,
+.Xr resolver 3 ,
.Xr hosts 5 ,
.Xr resolv.conf 5 ,
.Xr services 5 ,
.Xr hostname 7 ,
.Xr named 8
-.Pp
.Rs
.%A R. Gilligan
.%A S. Thomson
@@ -263,11 +179,14 @@ The error code can be found in errno.
.%D March 1999
.Re
.Rs
-.%A Tatsuya Jinmei
-.%A Atsushi Onoe
-.%T "An Extension of Format for IPv6 Scoped Addresses"
+.%A S. Deering
+.%A B. Haberman
+.%A T. Jinmei
+.%A E. Nordmark
+.%A B. Zill
+.%T "IPv6 Scoped Address Architecture"
.%R internet draft
-.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
+.%N draft-ietf-ipv6-scoping-arch-02.txt
.%O work in progress material
.Re
.Rs
@@ -276,28 +195,24 @@ The error code can be found in errno.
.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
.%D June 2000
.Re
-.\"
.Sh STANDARDS
The
.Fn getnameinfo
-function is defined in IEEE POSIX 1003.1g draft specification,
-and documented in
-.Dq Basic Socket Interface Extensions for IPv6
-.Pq RFC 2553 .
-.\"
-.Sh HISTORY
-The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
-.\"
+function is defined by the
+.St -p1003.1g-2000
+draft specification and documented in
+.Tn "RFC 2553" ,
+.Dq Basic Socket Interface Extensions for IPv6 .
.Sh CAVEATS
.Fn getnameinfo
-returns both numeric and FQDN notation of the address specified in
+can return both numeric and FQDN forms of the address specified in
.Fa sa .
-There is no return value that indicates if the string returned in
+There is no return value that indicates whether the string returned in
.Fa host
is a result of binary to numeric-text translation (like
.Xr inet_ntop 3 ) ,
-or the result of DNS reverse lookup.
-Therefore, malicious parties could set up a PTR record like below:
+or is the result of a DNS reverse lookup.
+Because of this, malicious parties could set up a PTR record as follows:
.Bd -literal -offset indent
1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
.Ed
@@ -308,13 +223,14 @@ into believing that
.Fa sa
is
.Li 10.1.1.1
-when it actually is
+when it is actually
.Li 127.0.0.1 .
.Pp
To prevent such attacks, the use of
.Dv NI_NAMEREQD
-is recommended when you use the result of
+is recommended when the result of
.Fn getnameinfo
+is used
for access control purposes:
.Bd -literal -offset indent
struct sockaddr *sa;
@@ -326,13 +242,13 @@ int error;
error = getnameinfo(sa, salen, addr, sizeof(addr),
NULL, 0, NI_NAMEREQD);
if (error == 0) {
- memset(\*[Am]hints, 0, sizeof(hints));
+ memset(&hints, 0, sizeof(hints));
hints.ai_socktype = SOCK_DGRAM; /*dummy*/
hints.ai_flags = AI_NUMERICHOST;
- if (getaddrinfo(addr, "0", \*[Am]hints, \*[Am]res) == 0) {
+ if (getaddrinfo(addr, "0", &hints, &res) == 0) {
/* malicious PTR record */
freeaddrinfo(res);
- printf("bogus PTR record\\n");
+ printf("bogus PTR record\en");
return -1;
}
/* addr is FQDN as a result of PTR lookup */
@@ -342,8 +258,14 @@ if (error == 0) {
NULL, 0, NI_NUMERICHOST);
}
.Ed
-.\"
.Sh BUGS
-The current implementation is not thread-safe.
-.Pp
-The text was shamelessly copied from RFC 2553.
+The implementation of
+.Fn getnameinfo
+is not thread-safe.
+.\".Pp
+.\".Ox
+.\"intentionally uses a different
+.\".Dv NI_MAXHOST
+.\"value from what
+.\".Tn "RFC 2553"
+.\"suggests, to avoid buffer length handling mistakes.