Improve some protocol details in pcap-filter(7).

Address point 2 and progress point 5 of GH bug report #326.

In the "ip proto protocol" section omit the "icmp6" protocol name,
explain the implicit involvement of getprotobyname() and give two
OS-specific names for IGRP.  In the "ip6 proto protocol" section give
"ipv6-icmp" as the proper protocol name (not a keyword).  In the index
operation description add "icmp6" to the list of supported protocol
layers.

Add two entries with the meaning of "icmp" and "icmp6" abbreviations.
In the list of abbreviations for "proto \protocol" remove "icmp" because
it never was and should not be the implemented behaviour; add "pim",
"ah" and "esp" because that has been the implemented behaviour since
commit 7fe3c11 in 1999.

Reformat and sort some lists alphabetically, update the timestamp.

diff --git a/CHANGES b/CHANGES
index a2890e0d860f12850658c28c5527e7bb72f70c05..cdb2c9207c70b2005b9d6fc64e326845ca5bb525 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -13,6 +13,8 @@ Monthday, Month DD, YYYY:
         "link-layer type plus other stuff" is non-zero.
     rpcap:
       Support user names and passwords in rpcap:// and rpcaps:// URLs.
+    Documentation:
+      Improve some protocol details in pcap-filter(7).
 
 Monthday, Month DD, YYYY:
   Summary for 1.10.2 libpcap release (so far!)

diff --git a/pcap-filter.manmisc.in b/pcap-filter.manmisc.in
index 5fce8043919c0184ad3bc968c63d628dfffa356a..ffc717fbc2182381f6aa2f94d9764e679eb1db84 100644 (file)
--- a/pcap-filter.manmisc.in
+++ b/pcap-filter.manmisc.in
@@ -18,7 +18,7 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
-.TH PCAP-FILTER @MAN_MISC_INFO@ "4 January 2022"
+.TH PCAP-FILTER @MAN_MISC_INFO@ "12 June 2022"
 .SH NAME
 pcap-filter \- packet filter syntax
 .br
@@ -290,20 +290,53 @@ This is equivalent to:
 True if the packet is an IPv4 packet (see
 .BR ip (4P))
 of protocol type \fIprotocol\fP.
-\fIProtocol\fP can be a number or one of the names
-\fBicmp\fP, \fBicmp6\fP, \fBigmp\fP, \fBigrp\fP, \fBpim\fP, \fBah\fP,
-\fBesp\fP, \fBvrrp\fP, \fBsctp\fP, \fBudp\fP, or \fBtcp\fP.
-Note that the identifiers \fBtcp\fP, \fBudp\fP, \fBsctp\fP and \fBicmp\fP
+\fIProtocol\fP can be a number or one of the names recognized by
+.BR getprotobyname (3)
+(as in e.g. `\fBgetent\fR(1) protocols'), typically from an entry in
+.IR \%/etc/protocols ,
+for example:
+.BR ah ,
+.BR esp ,
+.B eigrp
+(only in Linux, FreeBSD and NetBSD),
+.BR icmp ,
+.BR igmp ,
+.B igrp
+(only in OpenBSD),
+.BR pim ,
+.BR sctp ,
+.BR tcp ,
+.B udp
+or
+.BR vrrp .
+Note that most of these example identifiers
 are also keywords and must be escaped via backslash (\\).
 Note that this primitive does not chase the protocol header chain.
+.IP "\fBicmp\fR"
+Abbreviation for:
+.in +.5i
+.nf
+\fBip proto\fR 1
+.fi
+.in -.5i
 .IP "\fBip6 proto \fIprotocol\fR"
 True if the packet is an IPv6 packet of protocol type \fIprotocol\fP.
+Note that the IPv6 variant of ICMP uses a different protocol number, named
+.B \%ipv6-icmp
+in Linux, FreeBSD, NetBSD, OpenBSD, illumos and Solaris.
 Note that this primitive does not chase the protocol header chain.
+.IP "\fBicmp6\fR"
+Abbreviation for:
+.in +.5i
+.nf
+\fBip6 proto\fR 58
+.fi
+.in -.5i
 .IP "\fBproto \fIprotocol\fR"
 True if the packet is an IPv4 or IPv6 packet of protocol type
 \fIprotocol\fP.  Note that this primitive does not chase the protocol
 header chain.
-.IP  "\fBtcp\fR, \fBudp\fR, \fBicmp\fR, \fBsctp\fR"
+.IP  "\fBah\fR, \fBesp\fR, \fBpim\fR, \fBsctp\fR, \fBtcp\fR, \fBudp\fR"
 Abbreviations for:
 .in +.5i
 .nf
@@ -838,10 +871,37 @@ To access data inside the packet, use the following syntax:
 \fIproto\fB [ \fIexpr\fB : \fIsize\fB ]\fR
 .fi
 .in -.5i
-\fIProto\fR is one of \fBether, fddi, tr, wlan, ppp, slip, link,
-ip, arp, rarp, tcp, udp, sctp, icmp, ip6\fR or \fBradio\fR, and
+.I Proto
+is one of
+.BR arp ,
+.BR ether ,
+.BR fddi ,
+.BR icmp ,
+.BR icmp6 ,
+.BR ip ,
+.BR ip6 ,
+.BR link ,
+.BR ppp ,
+.BR radio ,
+.BR rarp ,
+.BR sctp ,
+.BR slip ,
+.BR tcp ,
+.BR tr ,
+.B udp
+or
+.BR wlan ,
+and
 indicates the protocol layer for the index operation.
-(\fBether, fddi, wlan, tr, ppp, slip\fR and \fBlink\fR all refer to the
+.RB ( ether ,
+.BR fddi ,
+.BR link ,
+.BR ppp ,
+.BR slip ,
+.B tr
+and
+.BR wlan
+all refer to the
 link layer. \fBradio\fR refers to the "radio header" added to some
 802.11 captures.)
 Note that \fBtcp\fR, \fBudp\fR and other upper-layer protocol types only