Further emphasize its non-portability, and give a use case.

Further emphasize that it works only on Linux, and only works there with
regular network interfaces.

Note that if some packets have a socket-layer protocol type that differs
from the protocol type in the link-layer header, you can only restrict
capture to those packets by using pcap_set_protocol().  (That's the
Arista sFlow-sampled packets case.)

1 files changed, 15 insertions, 1 deletions

diff --git a/pcap_set_protocol.3pcap b/pcap_set_protocol.3pcap
index 878ba1a1..9d4a2316 100644
--- a/pcap_set_protocol.3pcap
+++ b/pcap_set_protocol.3pcap
@@ -31,6 +31,7 @@ int pcap_set_protocol(pcap_t *p, int protocol);
 .ft
 .fi
 .SH DESCRIPTION
+On network interface devices on Linux,
 .B pcap_set_protocol()
 sets the protocol to be used in the
 .BR socket (2)
@@ -44,10 +45,23 @@ is non-zero, packets of that protocol will be captured when the
 handle is activated, otherwise, all packets will be captured.  This
 function is only provided on Linux, and, if it is used on any device
 other than a network interface, it will have no effect.
+.LP
+It should not be used in portable code; instead, a filter should be
+specified with
+.BR pcap_setfilter() .
+.LP
+If a given network interface provides a standard link-layer header, with
+a standard packet type, but provides some packet types with a different
+socket-layer protocol type from the one in the link-layer header, that
+packet type cannot be filtered with a filter specified with
+.B pcap_setfilter()
+but can be filtered by specifying the socket-layer protocol type using
+.BR pcap_set_protocol() .
 .SH RETURN VALUE
 .B pcap_set_protocol()
 returns 0 on success or
 .B PCAP_ERROR_ACTIVATED
 if called on a capture handle that has been activated.
 .SH SEE ALSO
-pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP)
+pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP), socket(2),
+pcap_setfilter(3PCAP)