Documentation: Document implementation-specific details for libpcap functions

[dmiller-nmap]

Some libpcap functions (pcap_stat() for instance) are portable but have different behavior on different platforms. Npcap's documentation should make it easy to find Npcap's specific behavior in all of these cases.

We will want to ensure this gets rendered to the HTML docs in a way that links to and from the appropriate libpcap man pages.

[guyharris]

Libpcap's documentation should have that information.

(And there should be a new API that 1) allows the caller to specify desired statistics by providing a list of pcapng Interface Statistics Block option values for them, 2) allows the implementation to return only the statistics that it can provide, with new statistics added, as necessary, to the ISB to ensure that none of the statistics have one value when supplied by Linux and another value when supplied by *BSD/macOS and yet another value when supplied by Soarlis and yet another value when supplied by Npcap and..., and 3) allows 64-bit values to be supplied.)

[dmiller-nmap]

@guyharris Since libpcap is portable/multiplatform, I assumed that the general guidance of "this may vary by platform" was good enough for there. At runtime, libpcap may not even be able to distinguish between Npcap and WinPcap, and there is a distinction between the two in regard to the reasons for dropped packets, at least since Npcap 0.9991. We will end up writing this guidance regardless, and if libpcap wants to include/copy it, we can work that out later.

The extensible stats API is very interesting; WinPcap had a PacketGetStatsEx() function that was supposed to be extensible to support remote pcap stats, but I don't know if libpcap uses it under the hood. Could you open a new enhancement request for that idea? That and the timestamp API stuff in #174 will probably wait until after we have a stable Npcap 1.0, but I'm excited for them nonetheless.

[bubbasnmp]

(Related to #174 ?)

C:\>dumpcap --list-time-stamp-types
Timestamp types of the interface (use option --time-stamp-type to set):
  host (Host)
  host_hiprec_unsynced (Host, high precision, not synced with system time)
  host_lowprec (Host, low precision)
  host_hiprec (Host, high precision)

PCAP_TSTAMP_HOST_HIPREC_UNSYNCED - host_hiprec_unsynced is listed on the tcpdump man page but not the npcap page.
Typo or different implementations?

[guyharris]

The full set of time stamp types that the libpcap API defines, as of the current state of the main branch of libpcap, is:

• PCAP_TSTAMP_HOST - host-provided, unknown characteristics
• PCAP_TSTAMP_HOST_LOWPREC - host-provided, low precision, synced with the system clock
• PCAP_TSTAMP_HOST_HIPREC - host-provided, high precision, synced with the system clock
• PCAP_TSTAMP_ADAPTER - device-provided, synced with the system clock
• PCAP_TSTAMP_ADAPTER_UNSYNCED - device-provided, not synced with the system clock
• PCAP_TSTAMP_HOST_HIPREC_UNSYNCED - host-provided, high precision, not synced with the system clock

There is no guarantee that any given adapter, on any given OS, will provide all of them.

The libpcap 1.10.x pcap-tstamp man page describes PCAP_TSTAMP_HOST_HIPREC_UNSYNCED; the npcap pcap-tstamp man page needs to be updated.

[dmiller-nmap]

@bubbasnmp We haven't regenerated the docs on the web version of the Npcap Guide yet. The version in the Npcap SDK ought to match libpcap's, and we will be updating the website this week.