Clarify the lifetime of the packet header and data when reading packets.

(Yes, I know - I'm using "data" as a collective noun. :-))

2 files changed, 25 insertions, 3 deletions

diff --git a/pcap_loop.3pcap b/pcap_loop.3pcap
index 70cfaa02..da306931 100644
--- a/pcap_loop.3pcap
+++ b/pcap_loop.3pcap
@@ -109,7 +109,12 @@ pointer to the first
 (as given in the
 .I struct pcap_pkthdr
 a pointer to which is passed to the callback routine)
-bytes of data from the packet.
+bytes of data from the packet.  The
+.I struct pcap_pkthdr
+and the packet data are not to be freed by the callback routine, and are
+not guaranteed to be valid after the callback routine returns; if the
+code needs them to be valid after the callback, it must make a copy of
+them.
 .SH RETURN VALUE
 .B pcap_loop()
 returns 0 if
diff --git a/pcap_next_ex.3pcap b/pcap_next_ex.3pcap
index 50ad198a..922efe2a 100644
--- a/pcap_next_ex.3pcap
+++ b/pcap_next_ex.3pcap
@@ -45,7 +45,16 @@ argument is set to point to the
 struct for the packet, and the
 pointer pointed to by the
 .I pkt_data
-argument is set to point to the data in the packet.
+argument is set to point to the data in the packet.  The
+.I struct pcap_pkthdr
+and the packet data are not to be freed by the caller, and are not
+guaranteed to be valid after the next call to
+.BR pcap_next_ex() ,
+.BR pcap_next() ,
+.BR pcap_loop() ,
+or
+.BR pcap_dispatch() ;
+if the code needs them to remain valid, it must make a copy of them.
 .PP
 .B pcap_next()
 reads the next packet (by calling
@@ -54,7 +63,15 @@ with a
 .I cnt
 of 1) and returns a
 .I u_char
-pointer to the data in that packet.
+pointer to the data in that packet.  The
+packet data is not to be freed by the caller, and is not
+guaranteed to be valid after the next call to
+.BR pcap_next_ex() ,
+.BR pcap_next() ,
+.BR pcap_loop() ,
+or
+.BR pcap_dispatch() ;
+if the code needs it to remain valid, it must make a copy of it.
 The
 .I pcap_pkthdr
 structure pointed to by