man: Document devices, interfaces and "any" better.

In pcap_create(3PCAP) and pcap_open_live(3PCAP) spell device/interface
and replace an explanation of the difference with a reference to
pcap_findalldevs(3PCAP).

In the latter man page remove the text that used to say "does not have
sufficient privileges... those devices will not appear" since libpcap
1.1.1 because it does not seem to match even what old libpcap versions
implemented (e.g. skip only if IFF_UP is not set in fad-gifc.c).  Add a
paragraph to explain the difference between listing devices and
activating a device in the current implementation.  Explain that a
capture device is a generic case of a network interface and how the
"any" pseudo-interface relates with network interfaces.  Show that a
device name can be used with pcap_create() too.

This resolves GitHub bug report #1055.

Author: infrastation

CHANGES

@@ -68,6 +68,7 @@ DayOfTheWeek, Month DD, YYYY / The Tcpdump Group
       pcap_lib_version(3PCAP): Add details and examples.
       Discuss Linux BPF extensions in the man pages.
       Note endianness in pcap_compile(3PCAP) and pcap_lookupnet(3PCAP).
+      man: Document devices, interfaces and "any" better.
     Building and testing:
       Apply GNU Hurd support patch from the Debian package.
       CI: Introduce and use LIBPCAP_CMAKE_TAINTED.

pcap_create.3pcap

@@ -17,7 +17,7 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
-.TH PCAP_CREATE 3PCAP "6 September 2024"
+.TH PCAP_CREATE 3PCAP "11 March 2025"
 .SH NAME
 pcap_create \- create a live capture handle
 .SH SYNOPSIS
@@ -37,18 +37,14 @@ pcap_t *pcap_create(const char *source, char *errbuf);
 .fi
 .SH DESCRIPTION
 .BR pcap_create ()
-is used to create a packet capture handle to look
-at packets on the network.
+is used to create a packet capture handle to capture packets on a device
+(typically a network interface, see
+.BR \%pcap_findalldevs (3PCAP)
+for a more detailed explanation).
 .I source
-is a string that specifies the network device to open; on all supported Linux
-systems, as well as on recent versions of macOS and Solaris, a
-.I source
-argument of "any" or
+is a string that specifies the capture device to open, in this function
 .B NULL
-can be used to capture packets from all network interfaces.  The latter should
-not be confused with all available capture devices as seen by
-.BR pcap_findalldevs (3PCAP),
-which may also include D-Bus, USB etc.
+means the same as the string "any".
 .I errbuf
 is a buffer large enough to hold at least
 .B PCAP_ERRBUF_SIZE

pcap_findalldevs.3pcap

@@ -17,7 +17,7 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
-.TH PCAP_FINDALLDEVS 3PCAP "9 August 2024"
+.TH PCAP_FINDALLDEVS 3PCAP "11 March 2025"
 .SH NAME
 pcap_findalldevs, pcap_freealldevs \- get a list of capture devices, and
 free that list
@@ -39,26 +39,47 @@ void pcap_freealldevs(pcap_if_t *alldevs);
 .fi
 .SH DESCRIPTION
 .BR pcap_findalldevs ()
-constructs a list of network devices that can be opened with
-.BR pcap_create (3PCAP)
+constructs a list of packet capture devices that potentially can be opened
+with
+.BR \%pcap_create (3PCAP)
 and
-.BR pcap_activate (3PCAP)
+.BR \%pcap_activate (3PCAP)
 or with
-.BR pcap_open_live (3PCAP).
-(Note that there may be network devices that cannot be opened by the
-process calling
-.BR pcap_findalldevs (),
-because, for example, that process does not have sufficient privileges
-to open them for capturing; if so, those devices will not appear on the
-list.)
+.BR \%pcap_open_live (3PCAP).
 .I alldevsp
 is a pointer to a
 .BR "pcap_if_t *" ;
 .I errbuf
 is a buffer large enough to hold at least
-.B PCAP_ERRBUF_SIZE
+.B \%PCAP_ERRBUF_SIZE
 chars.
 .PP
+The most common type of a capture device is a regular network interface, in
+which case the capture device name is the same as the OS network interface
+name, for example, "eth0".  All supported Linux systems, as well as recent
+versions of macOS and Solaris, implement a special "any" pseudo-interface,
+which captures packets from all regular network interfaces and does not
+support promiscuous mode.  If the "any" pseudo-interface is available, the
+list of capture devices includes it.  What is considered a regular network
+interface is an implementation detail of the OS (for example, on Linux this
+includes SocketCAN devices), so packets captured on the "any" pseudo-interface
+may represent more different network protocols than expected.  The list of
+capture devices, depending on how libpcap was compiled and how the host is
+configured, often also includes at least some of the following types:
+Bluetooth, DAG, D-Bus, Netlink, SNF and USB.
+.PP
+For most capture device types enumeration of devices does not require special
+privileges or a specific device state (i.e. being "up" or ready in any other
+sense).  However, capturing of packets on a device usually depends on some
+conditions, so
+.BR \%pcap_findalldevs ()
+may list devices that a subsequent call to
+.BR pcap_activate ()
+would reject -- then, for example, the error code
+.B \%PCAP_ERROR_PERM_DENIED
+would make the same sense as not being able to read from a particular file in
+a directory that allows to list the files.  This is the intended design.
+.PP
 If
 .BR pcap_findalldevs ()
 succeeds, the pointer pointed to by
@@ -80,6 +101,8 @@ for the last element of the list
 .TP
 .B name
 a pointer to a string giving a name for the device to pass to
+.BR pcap_create ()
+or
 .BR pcap_open_live ()
 .TP
 .B description

pcap_open_live.3pcap

@@ -17,7 +17,7 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
-.TH PCAP_OPEN_LIVE 3PCAP "4 March 2024"
+.TH PCAP_OPEN_LIVE 3PCAP "11 March 2025"
 .SH NAME
 pcap_open_live \- open a device for capturing
 .SH SYNOPSIS
@@ -38,18 +38,14 @@ pcap_t *pcap_open_live(const char *device, int snaplen,
 .fi
 .SH DESCRIPTION
 .BR pcap_open_live ()
-is used to obtain a packet capture handle to look
-at packets on the network.
+is used to obtain a packet capture handle to capture packets on a device
+(typically a network interface, see
+.BR \%pcap_findalldevs (3PCAP)
+for a more detailed explanation).
 .I device
-is a string that specifies the network device to open; on all supported Linux
-systems, as well as on recent versions of macOS and Solaris, a
-.I device
-argument of "any" or
+is a string that specifies the capture device to open, in this function
 .B NULL
-can be used to capture packets from all network interfaces.  The latter should
-not be confused with all available capture devices as seen by
-.BR pcap_findalldevs (3PCAP),
-which may also include D-Bus, USB etc.
+means the same as the string "any".
 .PP
 .I snaplen
 specifies the snapshot length to be set on the handle.  If the packet
@@ -58,7 +54,7 @@ sufficient for most devices, but D-Bus devices require a value of 128MiB
 (128*1024*1024).
 .PP
 .I promisc
-specifies whether the interface is to be put into promiscuous mode.
+specifies whether the device is to be put into promiscuous mode.
 If
 .I promisc
 is non-zero, promiscuous mode will be set, otherwise it will not be set.