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:

NetBSD Home
NetBSD PR Database Search

(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.