[src/netbsd-1-5]: src/lib/libc/net pullup 1.12 -> 1.15 (approved by releng-1-5)

[itojun <itojun%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e394746ef113
branches:  netbsd-1-5
changeset: 488791:e394746ef113
user:      itojun <itojun%NetBSD.org@localhost>
date:      Fri Jul 28 14:08:15 2000 +0000

description:
pullup 1.12 -> 1.15 (approved by releng-1-5)
give pitfall examples.
in response to couple of PRs including 10666.  sync with kame.

diffstat:

 lib/libc/net/getaddrinfo.3 |  67 +++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 64 insertions(+), 3 deletions(-)

diffs (88 lines):

diff -r 62523e6f26b2 -r e394746ef113 lib/libc/net/getaddrinfo.3
--- a/lib/libc/net/getaddrinfo.3        Fri Jul 28 12:42:59 2000 +0000
+++ b/lib/libc/net/getaddrinfo.3        Fri Jul 28 14:08:15 2000 +0000
@@ -1,5 +1,5 @@
-.\"    $NetBSD: getaddrinfo.3,v 1.10.4.2 2000/07/03 22:35:41 thorpej Exp $
-.\"    $KAME: getaddrinfo.3,v 1.15 2000/06/30 16:46:00 itojun Exp $
+.\"    $NetBSD: getaddrinfo.3,v 1.10.4.3 2000/07/28 14:08:15 itojun Exp $
+.\"    $KAME: getaddrinfo.3,v 1.21 2000/07/25 04:49:42 itojun Exp $
 .\"
 .\" Copyright (c) 1983, 1987, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -271,6 +271,67 @@
 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:
@@ -518,7 +579,7 @@
 .%A Atsushi Onoe
 .%T "An Extension of Format for IPv6 Scoped Addresses"
 .%R internet draft
-.%N draft-ietf-ipngwg-scopedaddr-format-01.txt
+.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 .%O work in progress material
 .Re
 .Rs