NetBSD Problem Report #39327
From Ephaeton@gmx.net Sat Aug 9 18:35:10 2008
Return-Path: <Ephaeton@gmx.net>
Received: from mail.netbsd.org (mail.netbsd.org [204.152.190.11])
by narn.NetBSD.org (Postfix) with ESMTP id 645D863BB81
for <gnats-bugs@gnats.NetBSD.org>; Sat, 9 Aug 2008 18:35:10 +0000 (UTC)
Message-Id: <20080809183506.C617CD626@circe.entropie.net>
Date: Sat, 9 Aug 2008 20:35:06 +0200 (CEST)
From: Ephaeton@gmx.net
Reply-To: Ephaeton@gmx.net
To: gnats-bugs@gnats.NetBSD.org
Subject: incoherent socket man pages
X-Send-Pr-Version: 3.95
>Number: 39327
>Category: misc
>Synopsis: incoherent socket man pages
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: misc-bug-people
>State: open
>Class: doc-bug
>Submitter-Id: net
>Arrival-Date: Sat Aug 09 18:40:00 +0000 2008
>Last-Modified: Fri May 22 19:45:02 +0000 2009
>Originator: Martin S. Weber
>Release: NetBSD 4.99.69
>Organization:
>Environment:
System: NetBSD circe.entropie.net 4.99.69 NetBSD 4.99.69 (GENERIC) #2: Mon Jul 14 16:54:25 CEST 2008 root@rfhinf038:/fsim/data/netbsd/obj/sys/arch/i386/compile/GENERIC i386
Architecture: i386
Machine: i386
>Description:
when reading socket(2), it says:
The protocol specifies a particular protocol to be used with the socket.
Normally only a single protocol exists to support a particular socket
type within a given protocol family. However, it is possible that many
protocols may exist, in which case a particular protocol must be speci-
fied in this manner. The protocol number to use is particular to the
communication domain in which communication is to take place; see
protocols(5).
I.e. there exists one set of protocol parameters per protocol family (or
in other words matching the arguments of socket(2), per "domain").
So you'd expect mention of the protocol family aka domain in protocols(5).
It's there, too -- "the known protocols used in the DARPA Internet."
(aka PF_INET) So let's have a look at /etc/protocols ...
First it starts babbling about IPV6 (which isn't PF_INET aka DARPA Internet),
then it continues to describe some protocols that are clearly IPv6.
These aren't for PF_INET, but for PF_INET6 ? From their comments and names,
I'd guess the latter. From them being in /etc/protocols, it *must* be PF_INET
as protocols(5) refers to the protocols as "DARPA Internet" (aka PF_INET)
protocols.
>How-To-Repeat:
man 2 socket , read
man 5 protocols , read
view /etc/protocols , read
>Fix:
Change protocols(5) to not talk about "DARPA Internet" protocols or add
a field in /etc/protocols to tell for which protocol family (aka domain
in socket(2)) the protocol really is.
>Audit-Trail:
From: Jukka Ruohonen <jruohonen@iki.fi>
To: gnats-bugs@NetBSD.org
Cc:
Subject: Re: misc/39327
Date: Fri, 22 May 2009 09:41:21 +0300
I think this is valid, i.e. in 2009 it is absurd to refer to "the DARPA
Internet" with the /etc/protocols-file.
Could this be closed with the following diff?
Index: protocols.5
===================================================================
RCS file: /cvsroot/src/share/man/man5/protocols.5,v
retrieving revision 1.7
diff -u -p -r1.7 protocols.5
--- protocols.5 7 Aug 2003 10:31:17 -0000 1.7
+++ protocols.5 22 May 2009 06:36:56 -0000
@@ -39,7 +39,6 @@
The
.Nm protocols
file contains information regarding the known protocols used in the
-.Tn DARPA
Internet. For each protocol a single line should be present
with the following information:
.Bd -unfilled -offset indent
From: "Martin S. Weber" <Ephaeton@gmx.net>
To: gnats-bugs@NetBSD.org
Cc: misc-bug-people@netbsd.org, gnats-admin@netbsd.org,
netbsd-bugs@netbsd.org
Subject: Re: misc/39327
Date: Fri, 22 May 2009 11:09:07 -0400
On Fri, May 22, 2009 at 06:45:02AM +0000, Jukka Ruohonen wrote:
> The following reply was made to PR misc/39327; it has been noted by GNATS.
>
> From: Jukka Ruohonen <jruohonen@iki.fi>
> To: gnats-bugs@NetBSD.org
> Cc:
> Subject: Re: misc/39327
> Date: Fri, 22 May 2009 09:41:21 +0300
>
> I think this is valid, i.e. in 2009 it is absurd to refer to "the DARPA
> Internet" with the /etc/protocols-file.
>
> Could this be closed with the following diff?
> (.. diff omitted ..)
Well, it's true that it shouldn't be "the DARPA internet" anylonger, but
what about the other part of the fix suggestion, i.e. document in
/etc/procotols which domain (by socket(2) parlese) the protocol is for?
-Martin
From: Jukka Ruohonen <jruohonen@iki.fi>
To: gnats-bugs@NetBSD.org
Cc:
Subject: Re: misc/39327
Date: Fri, 22 May 2009 20:04:48 +0300
5AOn Fri, May 22, 2009 at 11:09:07AM -0400, Martin S. Weber wrote:
> Well, it's true that it shouldn't be "the DARPA internet" anylonger, but
> what about the other part of the fix suggestion, i.e. document in
> /etc/procotols which domain (by socket(2) parlese) the protocol is for?
I am not sure whether I follow you with the other part.
1. I think it is not so easy nor reasonable for a single operating system to
change '/etc/protocols' because it comes from IANA, a.k.a. the Internet
Assigned Numbers Authority. Functions like getprotobyname(3) also use
'/etc/protocols' as a lookup; changing it will break a lot of things.
2. Generally the file is not meant as a reference for the domain-parameter
in socket(2), but rather as a reference for the number in the protocol-field
of IPv4 header (or next header -field in IPv6), as described also in the
file itsef. Even if such change would be made, there is no mapping between
the AF_-constants and the file (surely e.g. TCP can be used both with
AF_INET and AF_INET6).
3. Moreover, I think the socket(2) manual page does not rightly give any
impression that one should look to '/etc/protocols' for the AF_-constants.
- Jukka.
From: "Martin S. Weber" <Ephaeton@gmx.net>
To: gnats-bugs@NetBSD.org
Cc: misc-bug-people@netbsd.org, gnats-admin@netbsd.org,
netbsd-bugs@netbsd.org
Subject: Re: misc/39327
Date: Fri, 22 May 2009 13:14:03 -0400
On Fri, May 22, 2009 at 05:05:03PM +0000, Jukka Ruohonen wrote:
> The following reply was made to PR misc/39327; it has been noted by GNATS.
>
> From: Jukka Ruohonen <jruohonen@iki.fi>
> To: gnats-bugs@NetBSD.org
> Cc:
> Subject: Re: misc/39327
> Date: Fri, 22 May 2009 20:04:48 +0300
>
> 5AOn Fri, May 22, 2009 at 11:09:07AM -0400, Martin S. Weber wrote:
> > Well, it's true that it shouldn't be "the DARPA internet" anylonger, but
> > what about the other part of the fix suggestion, i.e. document in
> > /etc/procotols which domain (by socket(2) parlese) the protocol is for?
>
> I am not sure whether I follow you with the other part.
>
> 1. I think it is not so easy nor reasonable for a single operating system to
> change '/etc/protocols' because it comes from IANA, a.k.a. the Internet
> Assigned Numbers Authority. Functions like getprotobyname(3) also use
> '/etc/protocols' as a lookup; changing it will break a lot of things.
>
I understand that, but on the other hand even the IANA will not block
an improvement in a file they provide, will they?
> 2. Generally the file is not meant as a reference for the domain-parameter
> in socket(2), but rather as a reference for the number in the protocol-field
> of IPv4 header (or next header -field in IPv6), as described also in the
> file itsef. Even if such change would be made, there is no mapping between
> the AF_-constants and the file (surely e.g. TCP can be used both with
> AF_INET and AF_INET6).
>
I think there's some confusion here. I wasn't talking about the domain
parameter of socket(), but about its protocol parameter:
int
socket(int domain, int type, int protocol);
The domain parameter can be PF_INET, PF_INET6 and a lot of others, for
the _protocol_ parameter the manpage says, "The protocol number to use is
particular to the communication domain in which communication is to
take place; see protocols(5).".
That makes me think: There exists a mapping of domain parameters to
a set of usable protocol parameters. Look at protocols(5) (and thus
at /etc/protocols) to find out which. But /etc/protocols only documents
the possible protocols at all. Now if /etc/protocols had also a field
for the "communication domain in which communication is to take place",
there would be no doubt about usable protocols. Take "icmp 1 ICMP" for
instance. If it read "icmp 1 ICMP PF_INET" instead, it would be obvious
that icmp is not for PF_INET6. Actually even expanding the comment instead
of adding a new field to improve documentation on where this procotol
"belongs" would improve the situation in my opinion.
> 3. Moreover, I think the socket(2) manual page does not rightly give any
> impression that one should look to '/etc/protocols' for the AF_-constants.
>
AF_ ? The socket(2) man page only talks about PF_ constants (besides, I
personally never understood THEIR distinction but that is outside the scope
of this PR.)
-Martin
From: Jukka Ruohonen <jruohonen@iki.fi>
To: gnats-bugs@NetBSD.org
Cc:
Subject: Re: misc/39327
Date: Fri, 22 May 2009 20:39:55 +0300
On Fri, May 22, 2009 at 01:14:03PM -0400, Martin S. Weber wrote:
>
> That makes me think: There exists a mapping of domain parameters to
> a set of usable protocol parameters. Look at protocols(5) (and thus
> at /etc/protocols) to find out which. But /etc/protocols only documents
> the possible protocols at all. Now if /etc/protocols had also a field
> for the "communication domain in which communication is to take place",
> there would be no doubt about usable protocols. Take "icmp 1 ICMP" for
> instance. If it read "icmp 1 ICMP PF_INET" instead, it would be obvious
> that icmp is not for PF_INET6. Actually even expanding the comment instead
> of adding a new field to improve documentation on where this procotol
> "belongs" would improve the situation in my opinion.
Sure, I understand now and think you are right. But then again, someone
would need to push this to IANA. But note that there is a quite extensive
list of RFCs and other references in /etc/protocols in case a reader really
wonders if IPv4 ICMP can be used with IPv6, and so forth.
> AF_ ? The socket(2) man page only talks about PF_ constants (besides, I
> personally never understood THEIR distinction but that is outside the scope
> of this PR.)
Yes, that seems to go very deep into the history :-). (At least as mentioned
by Stevens, Fenner and Rudoff (2003, pp. 98-99) in their UNP.)
- Jukka.
From: "Martin S. Weber" <Ephaeton@gmx.net>
To: gnats-bugs@NetBSD.org
Cc: misc-bug-people@netbsd.org, gnats-admin@netbsd.org,
netbsd-bugs@netbsd.org
Subject: Re: misc/39327
Date: Fri, 22 May 2009 15:42:26 -0400
On Fri, May 22, 2009 at 05:45:02PM +0000, Jukka Ruohonen wrote:
> The following reply was made to PR misc/39327; it has been noted by GNATS.
>
> From: Jukka Ruohonen <jruohonen@iki.fi>
> To: gnats-bugs@NetBSD.org
> Cc:
> Subject: Re: misc/39327
> Date: Fri, 22 May 2009 20:39:55 +0300
>
> On Fri, May 22, 2009 at 01:14:03PM -0400, Martin S. Weber wrote:
> >
> > That makes me think: There exists a mapping of domain parameters to
> > a set of usable protocol parameters. Look at protocols(5) (and thus
> > at /etc/protocols) to find out which. But /etc/protocols only documents
> > the possible protocols at all. Now if /etc/protocols had also a field
> > for the "communication domain in which communication is to take place",
> > there would be no doubt about usable protocols. Take "icmp 1 ICMP" for
> > instance. If it read "icmp 1 ICMP PF_INET" instead, it would be obvious
> > that icmp is not for PF_INET6. Actually even expanding the comment instead
> > of adding a new field to improve documentation on where this procotol
> > "belongs" would improve the situation in my opinion.
>
> Sure, I understand now and think you are right. But then again, someone
> would need to push this to IANA. But note that there is a quite extensive
> list of RFCs and other references in /etc/protocols in case a reader really
> wonders if IPv4 ICMP can be used with IPv6, and so forth.
>
Yeah that's true and I really like the rfc references from protocols. But
it's always sort of true that if you read more you learn more... to me the
direct usefulness of /etc/protocols would sufficiently increase if either
another field with the symbolic name of the fitting 'domain' parameter for
socket(2) would be added, or if that symbolic name would be added to the
beginning of the comment in /etc/protocols. This augmented file then could
be pushed to iana as an improvement request. That leaves some questions:
- who does it? I don't think I have the expertise or fell home enough in
the netbsd source code to dig up everything easily but if no one else will
do it, I will ... sometime ...
- another field or comment? Adding another field at the end shouldn't break
functions reading out data line-wise and then field-wise, should it? that
also would have the benefit of the data being (more easily) available to
programs working with /etc/protocols (that ignore comments). Adding it in
the comment would "only" make the information available to a human reader,
but then again, that's the motivation for this PR - the human reader.
- no matter the questions above, who would tap the IANA? I wonder if they
accepted input from an individual "from outside" like me, but surely from
an OS "vendor" or even better, some NetBSD "community member" that is
directly involved with IANA?
Given you (Jukka) agree that augmenting /etc/protocols makes sense, I
think this PR should remain open until there are some answers on the above
points, while still the "DARPA" part can safely be cut from the manpages.
Thanks so far & regards,
-Martin
>Unformatted:
(Contact us)
$NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.8 2006/05/07 09:23:38 tsutsui Exp $
Copyright © 1994-2007
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.