Even more painful details explained.

Change-Id: I8cc4c4488f204f52d13caf99299a070ca0a250e0
Reviewed-on: https://code.wireshark.org/review/33073
Reviewed-by: Guy Harris <guy@alum.mit.edu>

1 files changed, 36 insertions, 6 deletions

diff --git a/wspcap.h b/wspcap.h
index 02121bc402..38a6bfc2c6 100644
--- a/wspcap.h
+++ b/wspcap.h
@@ -3,7 +3,23 @@
  * Wrapper around libpcap/WinPcap's pcap.h.
  *
  * If HAVE_PCAP_REMOTE is defined, it forces the WinPcap header files to
- * define things required for remote capture.
+ * define things required for remote capture, by defining HAVE_REMOTE.
+ *
+ * With current versions of the WinPcap or Npcap SDK, if:
+ *
+ *    1) you are building with any current WinPcap or Npcap SDK;
+ *    2) you do not define HAVE_REMOTE before including pcap.h (or
+ *       pcap/pcap.h);
+ *    3) you define a struct pcap_stat and pass it to a call to
+ *       pcap_stats();
+ *    4) the system you're running on has WinPcap, rather than Npcap,
+ *       installed;
+ *
+ * whatever is in memory after the struct pcap_stat may get overwritten,
+ * with unpredictable results, because the pcap_stats() implementation for
+ * WinPcap will assume that the structure has the additional members that
+ * are added if and only if HAVE_REMOTE is defined, and will fill them in,
+ * even if they're not there.
  *
  * Yes, this is q WinPcap bug; if your project has a public header file
  * that checks or otherwise uses a #define that's defined by your project's
@@ -11,12 +27,26 @@
  * appropriately when that header file is included, before its first use,
  * you have made a mistake.
  *
- * This bug is fixed in libpcap 1.9.0 or later, so any libpcap release
+ * In libpcap 1.7.0 and later, the pcap_stats() implementation for WinPcap
+ * will not fill those fields in; however, no WinPcap implementation was
+ * based on that recent a libpcap release, so they all have the bug.
+ *
+ * Npcap was originally based on libpcap 1.8.0, and later releases are
+ * based on later releases of libpcap, so they will not overwrite memory
+ * past the end of the structure.
+ *
+ * The header file bug is fixed in libpcap 1.9.0 or later - the fields
+ * are present on Windows, regardless of whether HAVE_REMOTE is defined
+ * or not when the header is included (and are not present on UN*X), so
+ * if you build with an SDK with libpcap 1.9.0 or later headers, you
+ * do not need to define HAVE_REMOTE before including pcap.h (including it
+ * will make no difference).
+ *
+ * No version of the WinPcap SDK provided libpcap 1.9.0-or-later headers.
+ * The Npcap SDK, as of SDK version 1.01, does not provide libpcap 1.9.0-
+ * or-later headers, even though newer versions of Npcap are based on
  * with remote capture support will not have this problem.  Newer versions
- * of Npcap are based on libpcap 1.9.0, but the Npcap SDK, as of SDK version
- * 1.01, doesn't provide header files from libpcap 1.9.0, so the bug is not
- * fixed there.  An issue has been filed against Npcap for that; the fix
- * will fix the bug in question.
+ * libpcap 1.9.0; an issue has been filed against Npcap for that.
  *
  * Wireshark - Network traffic analyzer
  * By Gerald Combs <gerald@wireshark.org>