mention getipnodeby* and get{addr,name}info are not thread-safe. (sync with kame)

s/.Os KAME/.Os/
comment From: Greg Thompson

6 files changed, 110 insertions, 21 deletions

diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3
index 2e608cd..1a0b5f4 100644
--- a/lib/libc/net/getaddrinfo.3
+++ b/lib/libc/net/getaddrinfo.3
@@ -1,7 +1,7 @@
-.\" Copyright (c) 1983, 1987, 1991, 1993
 .\"	$FreeBSD$
-.\"	$KAME: getaddrinfo.3,v 1.16 2000/07/05 08:18:42 itojun Exp $
+.\"	$KAME: getaddrinfo.3,v 1.22 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
@@ -36,7 +36,7 @@
 .\"
 .Dd May 25, 1995
 .Dt GETADDRINFO 3
-.Os KAME
+.Os
 .\"
 .Sh NAME
 .Nm getaddrinfo ,
@@ -270,6 +270,67 @@ is returned.
 This flag prevents any type of name resolution service (e.g., the DNS)
 from being called.
 .Pp
+The arguments to
+.Fn getaddrinfo
+must sufficiently be consistent and unambiguous.
+Here are pitfall cases you may encounter:
+.Bl -bullet
+.It
+.Fn getaddrinfo
+will raise error if members in 
+.Fa hints
+structure is not consistent.
+For example, for internet address families,
+.Fn getaddrinfo
+will raise error if you specify
+.Dv SOCK_STREAM
+to
+.Fa ai_socktype
+while you specify
+.Dv IPPROTO_UDP
+to
+.Fa ai_protocol .
+.It
+If you specify a
+.Fa servname
+which is defined only for certain
+.Fa ai_socktype ,
+.Fn getaddrinfo
+will raise error because the arguments are not consistent.
+For example,
+.Fn getaddrinfo
+will raise error if you ask for
+.Dq Li tftp
+service on
+.Dv SOCK_STREAM .
+.It
+For internet address families, if you specify
+.Fa servname
+while you set
+.Fa ai_socktype
+to
+.Dv SOCK_RAW ,
+.Fn getaddrinfo
+will raise error, because service names are not defined for the internet
+.Dv SOCK_RAW
+space.
+.It
+If you specify numeric
+.Fa servname ,
+while leaving
+.Fa ai_socktype
+and
+.Fa ai_protocol
+unspecified,
+.Fn getaddrinfo
+will raise error.
+This is because the numeric
+.Fa servname
+does not identify any socket type, and
+.Fn getaddrinfo
+is not allowed to glob the argument in such case.
+.El
+.Pp
 All of the information returned by
 .Fn getaddrinfo
 is dynamically allocated:
@@ -539,4 +600,6 @@ and documented in
 .Pq RFC2553 .
 .\"
 .Sh BUGS
+The current implementation is not thread-safe.
+.Pp
 The text was shamelessly copied from RFC2553.
diff --git a/lib/libc/net/getipnodebyname.3 b/lib/libc/net/getipnodebyname.3
index bb20406..618f5a3 100644
--- a/lib/libc/net/getipnodebyname.3
+++ b/lib/libc/net/getipnodebyname.3
@@ -1,3 +1,6 @@
+.\"	$FreeBSD$
+.\"	$KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $
+.\"
 .\" Copyright (c) 1983, 1987, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
@@ -30,12 +33,10 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)gethostbyname.3	8.4 (Berkeley) 5/25/95
-.\"     $Id: getipnodebyname.3,v 1.2 1999/09/13 16:04:51 itojun Exp $
-.\	$FreeBSD$
 .\"
 .Dd May 25, 1995
 .Dt GETIPNODEBYNAME 3
-.Os KAME
+.Os
 .\"
 .Sh NAME
 .Nm getipnodebyname ,
@@ -94,7 +95,7 @@ For
 .Fn getipnodebyname ,
 the
 .Ar name
-argument can be either a node name or a numeric address 
+argument can be either a node name or a numeric address
 string
 .Po
 i.e., a dotted-decimal IPv4 address or an IPv6 hex address
@@ -411,9 +412,9 @@ or
 .El
 .\"
 .Sh DIAGNOSTICS
-.Nm getipnodebyname
+.Fn getipnodebyname
 and
-.Nm getipnodebyaddr
+.Fn getipnodebyaddr
 returns
 .Dv NULL
 on errors.
@@ -432,8 +433,15 @@ The meanings of each error code are described in
 .Xr hostname 7 ,
 .Xr named 8
 .Pp
-R. Gilligan, S.  Thomson, J. Bound, and W. Stevens,
-``Basic Socket Interface Extensions for IPv6,'' RFC2553, March 1999.
+.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
 .\"
 .Sh HISTORY
 The implementation first appeared in KAME advanced networking kit.
@@ -442,8 +450,23 @@ The implementation first appeared in KAME advanced networking kit.
 .Fn getipnodebyname
 and
 .Fn getipnodebyaddr
-are documented in ``Basic Socket Interface Extensions for IPv6''
+are documented in
+.Dq Basic Socket Interface Extensions for IPv6
 .Pq RFC2553 .
 .\"
 .Sh BUGS
+.Fn getipnodebyname
+and
+.Fn getipnodebyaddr
+do not handle scoped IPv6 address properly.
+If you use these functions,
+your program will not be able to handle scoped IPv6 addresses.
+For IPv6 address manipulation,
+.Fn getaddrinfo 3
+and
+.Fn getnameinfo 3
+are recommended.
+.Pp
+The current implementation is not thread-safe.
+.Pp
 The text was shamelessly copied from RFC2553.
diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3
index 0b47857..113563f 100644
--- a/lib/libc/net/getnameinfo.3
+++ b/lib/libc/net/getnameinfo.3
@@ -1,5 +1,5 @@
 .\"	$FreeBSD$
-.\"	$KAME: getnameinfo.3,v 1.16 2000/07/05 08:22:04 itojun Exp $
+.\"	$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.
@@ -36,7 +36,7 @@
 .\"
 .Dd May 25, 1995
 .Dt GETNAMEINFO 3
-.Os KAME
+.Os
 .\"
 .Sh NAME
 .Nm getnameinfo
@@ -57,14 +57,15 @@ The
 .Fn getnameinfo
 function is defined for protocol-independent address-to-nodename translation.
 Its functionality is a reverse conversion of
-.Xr getaddrinfo 3
-and is similar to that of
+.Xr getaddrinfo 3 ,
+and implements similar functionality with
 .Xr gethostbyaddr 3
 and
-.Xr getservbyport 3 .
+.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 then returns text
+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.
@@ -303,6 +304,8 @@ and documented in
 .Pq 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
diff --git a/lib/libc/net/if_indextoname.3 b/lib/libc/net/if_indextoname.3
index 612ae1b..a0d4beb 100644
--- a/lib/libc/net/if_indextoname.3
+++ b/lib/libc/net/if_indextoname.3
@@ -34,7 +34,7 @@
 .\"
 .Dd May 21, 1998
 .Dt IF_NAMETOINDEX 3
-.Os KAME
+.Os
 .Sh NAME
 .Nm if_nametoindex ,
 .Nm if_indextoname ,
diff --git a/lib/libc/net/inet6_option_space.3 b/lib/libc/net/inet6_option_space.3
index 6c0e365..63cbfa5 100644
--- a/lib/libc/net/inet6_option_space.3
+++ b/lib/libc/net/inet6_option_space.3
@@ -34,7 +34,7 @@
 .\"
 .Dd December 10, 1999
 .Dt INET6_OPTION_SPACE 3
-.Os KAME
+.Os
 .\"
 .Sh NAME
 .Nm inet6_option_space ,
diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3
index 4c1e80a..26e5c35 100644
--- a/lib/libc/net/inet6_rthdr_space.3
+++ b/lib/libc/net/inet6_rthdr_space.3
@@ -34,7 +34,7 @@
 .\"
 .Dd December 10, 1999
 .Dt INET6_RTHDR_SPACE 3
-.Os KAME
+.Os
 .\"
 .Sh NAME
 .Nm inet6_rthdr_space ,