Make "{un}synced with the system clock" a property of more time stamp…

… types.

Define PCAP_TSTAMP_HOST_{LOW,HI}PREC as synced with the system clock;
add a new PCAP_TSTAMP_HOST_HIPREC_UNSYNCED type for high-precision time
stamps not necessarily synced with the system clock.

This should better match Npcap, including a proposed future "high
precision and synced with the system clock" time stamps for Npcap on
Windows 8 and later.

(This may still not match what FreeBSD offers, but at least it removes
an Npcap mismatch.)

pcap-tstamp.manmisc.in

@@ -110,9 +110,14 @@ system's clock.
 .TP 5
 .BR PCAP_TSTAMP_HOST_HIPREC " - " host_hiprec
 Time stamp provided by the host on which the capture is being done.
-This is a high-precision time stamp; it might or might not be
-synchronized with the host operating system's clock.  It might be more
-expensive to fetch than
+This is a high-precision time stamp, synchronized with the host
+operating system's clock. It might be more expensive to fetch than
+.BR PCAP_TSTAMP_HOST_LOWPREC .
+.TP 5
+.BR PCAP_TSTAMP_HOST_HIPREC_UNSYNCED " - " host_hiprec_unsynced
+Time stamp provided by the host on which the capture is being done.
+This is a high-precision time stamp, not synchronized with the host
+operating system's clock. It might be more expensive to fetch than
 .BR PCAP_TSTAMP_HOST_LOWPREC .
 .TP 5
 .BR PCAP_TSTAMP_ADAPTER " - " adapter
@@ -126,6 +131,18 @@ done.  This is a high-precision time stamp; it is not synchronized with
 the host operating system's clock.
 .RE
 .LP
+Time stamps synchronized with the system clock can go backwards, as the
+system clock can go backwards. If a clock is not in sync with the
+system clock, that could be because the system clock isn't keeping
+accurate time, because the other clock isn't keeping accurate time, or
+both.
+.LP
+Host-provided time stamps generally correspond to the time when the
+time-stamping code sees the packet; this could be some unknown amount of
+time after the first or last bit of the packet is received by the
+network adapter, due to batching of interrupts for packet arrival,
+queueing delays, etc..
+.LP
 By default, when performing a live capture or reading from a savefile,
 time stamps are supplied as seconds since January 1, 1970, 00:00:00 UTC,
 and microseconds since that seconds value, even if higher-resolution

pcap.c

@@ -3206,6 +3206,7 @@ static struct tstamp_type_choice tstamp_type_choices[] = {
 	{ "host_hiprec", "Host, high precision", PCAP_TSTAMP_HOST_HIPREC },
 	{ "adapter", "Adapter", PCAP_TSTAMP_ADAPTER },
 	{ "adapter_unsynced", "Adapter, not synced with system time", PCAP_TSTAMP_ADAPTER_UNSYNCED },
+	{ "host_hiprec_unsynced", "Host, high precision, not synced with system time", PCAP_TSTAMP_HOST_HIPREC_UNSYNCED },
 	{ NULL, NULL, 0 }
 };
 

pcap/pcap.h

@@ -360,19 +360,23 @@ PCAP_API int	pcap_set_protocol_linux(pcap_t *, int);
  *
  * A system that supports PCAP_TSTAMP_HOST is offering time stamps
  * provided by the host machine, rather than by the capture device,
- * but not committing to any characteristics of the time stamp;
- * it will not offer any of the PCAP_TSTAMP_HOST_ subtypes.
+ * but not committing to any characteristics of the time stamp.
  *
  * PCAP_TSTAMP_HOST_LOWPREC is a time stamp, provided by the host machine,
  * that's low-precision but relatively cheap to fetch; it's normally done
  * using the system clock, so it's normally synchronized with times you'd
  * fetch from system calls.
  *
  * PCAP_TSTAMP_HOST_HIPREC is a time stamp, provided by the host machine,
- * that's high-precision; it might be more expensive to fetch.  It might
- * or might not be synchronized with the system clock, and might have
+ * that's high-precision; it might be more expensive to fetch.  It is
+ * synchronized with the system clock.
+ *
+ * PCAP_TSTAMP_HOST_HIPREC_UNSYNCED is a time stamp, provided by the host
+ * machine, that's high-precision; it might be more expensive to fetch.
+ * It is not synchronized with the system clock, and might have
  * problems with time stamps for packets received on different CPUs,
- * depending on the platform.
+ * depending on the platform.  It might be more likely to be strictly
+ * monotonic than PCAP_TSTAMP_HOST_HIPREC.
  *
  * PCAP_TSTAMP_ADAPTER is a high-precision time stamp supplied by the
  * capture device; it's synchronized with the system clock.
@@ -392,11 +396,12 @@ PCAP_API int	pcap_set_protocol_linux(pcap_t *, int);
  * the packet is received by the network adapter, due to batching
  * of interrupts for packet arrival, queueing delays, etc..
  */
-#define PCAP_TSTAMP_HOST		0	/* host-provided, unknown characteristics */
-#define PCAP_TSTAMP_HOST_LOWPREC	1	/* host-provided, low precision */
-#define PCAP_TSTAMP_HOST_HIPREC		2	/* host-provided, high precision */
-#define PCAP_TSTAMP_ADAPTER		3	/* device-provided, synced with the system clock */
-#define PCAP_TSTAMP_ADAPTER_UNSYNCED	4	/* device-provided, not synced with the system clock */
+#define PCAP_TSTAMP_HOST			0	/* host-provided, unknown characteristics */
+#define PCAP_TSTAMP_HOST_LOWPREC		1	/* host-provided, low precision, synced with the system clock */
+#define PCAP_TSTAMP_HOST_HIPREC			2	/* host-provided, high precision, synced with the system clock */
+#define PCAP_TSTAMP_ADAPTER			3	/* device-provided, synced with the system clock */
+#define PCAP_TSTAMP_ADAPTER_UNSYNCED		4	/* device-provided, not synced with the system clock */
+#define PCAP_TSTAMP_HOST_HIPREC_UNSYNCED	5	/* host-provided, high precision, not synced with the system clock */
 
 /*
  * Time stamp resolution types.