pcap-savefile(5): Explain snapshot-based truncation. [skip ci]

Clarify that in a savefile the snapshot length indeed limits the maximum
packet size for both reading and writing, and that this is both the
intended and the implemented behaviour.  See GiHub issue #215.

diff --git a/pcap-savefile.manfile.in b/pcap-savefile.manfile.in
index bde0cfc671daa995d15dfc9e7ca6dab782478862..522867a1bab8441683157ed0aa9f3dee44c641da 100644 (file)
--- a/pcap-savefile.manfile.in
+++ b/pcap-savefile.manfile.in
@@ -17,7 +17,7 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"

-.TH PCAP-SAVEFILE @MAN_FILE_FORMATS@ "6 Jan 2025"
+.TH PCAP-SAVEFILE @MAN_FILE_FORMATS@ "21 Jan 2025"

 .SH NAME
 pcap-savefile \- libpcap savefile format
 .SH DESCRIPTION
 .SH NAME
 pcap-savefile \- libpcap savefile format
 .SH DESCRIPTION


@@ -102,14 +102,18 @@ implementations as "accuracy of timestamps".  Some older pcap file
 writers stored non-zero values in this field.
 .IP
 A 4-byte number giving the "snapshot length" of the capture; packets
 writers stored non-zero values in this field.
 .IP
 A 4-byte number giving the "snapshot length" of the capture; packets

-longer than the snapshot length are truncated to the snapshot length, so
-that, if the snapshot length is
+longer than the snapshot length are truncated to the snapshot length.
+Specifically, when libpcap is writing to a savefile (from a live packet
+capture or otherwise), if the savefile's snapshot length is

 .IR N ,
 .IR N ,

-only the first
+it writes to the savefile only the first

 .I N
 bytes of a packet longer than
 .I N
 .I N
 bytes of a packet longer than
 .I N

-bytes will be saved in the capture.
+bytes; when libpcap is reading from a savefile, it delivers at most
+.I N
+bytes for any packet in the savefile.  Other software that needs to access
+savefiles directly should implement the same logic.

 .IP
 A 4-byte number giving the link-layer header type for packets in the
 capture and optional additional information.
 .IP
 A 4-byte number giving the link-layer header type for packets in the
 capture and optional additional information.