Re: Error in the pcap_next_ex(3PCAP) man page

[Guy Harris <gharris () sonic net>]

On Mar 24, 2026, at 10:18 PM, Aaron Rainbolt <arraybolt3 () gmail com> wrote:

> In the "Return Value" section of the pcap_next_ex(3PCAP) manpage, it
> says that "pcap_next_ex() returns... PCAP_ERROR_BREAK if packets are
> being read from a ``savefile'' and there are no more packets to read
> from the savefile...". This is incorrect; the source code states that
> PCAP_ERROR_BREAK can be returned if the pcap_next_ex() call is
> interrupted by pcap_breakloop():
>
>    #define PCAP_ERROR_BREAK            -2      /* loop terminated by pcap_breakloop */
>
> And in practice, this is what happens in some code I wrote for testing
> a TCP-behavior-changing kernel module.

To quote the comment in pcap_next_ex():

                /*
                 * Return codes for pcapint_offline_read() are:
                 *   -  0: EOF
                 *   - -1: error
                 *   - >0: OK - result is number of packets read, so
                 *         it will be 1 in this case, as we've passed
                 *         a maximum packet count of 1
                 * The first one ('0') conflicts with the return code of
                 * 0 from pcap_read() meaning "no packets arrived before
                 * the timeout expired", so we map it to -2 so you can
                 * distinguish between an EOF from a savefile and a
                 * "no packets arrived before the timeout expired, try
                 * again" from a live capture.
                 */

(the original comment added when `pcap_next_ex()` just said "The first one ('0') conflicts with the return code of the 
pcap_read()"; I added the additional information to fully explain the problem).

This is ugly, but so are `pcap_next()` and `pcap_next_ex()`, in multiple ways.

The return of -2 predates the existence of pcap_breakloop(), so, when that return was added, it *wasn't* 
PCAP_ERROR_BREAK, it was just -2. The man page should just refer to it as -2, and perhaps note that this is *not* 
PCAP_ERROR_BREAK, and note that it's returned so that a program that uses pcap_next_ex() both with live captures and 
savefiles can distinguish between the two cases that return 0.
_______________________________________________
tcpdump-workers mailing list -- tcpdump-workers () lists tcpdump org
To unsubscribe send an email to tcpdump-workers-leave () lists tcpdump org
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s