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

[Guy Harris <gharris () sonic net>]

On Mar 26, 2026, at 6:58 AM, Denis Ovsienko <denis () ovsienko info> wrote:

> On Wed, 25 Mar 2026 10:40:39 -0700
> Guy Harris <gharris () sonic net> wrote:
>
> > 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.
>
> The problem stated in this thread seems to be that pcap_next_ex(3PCAP)
> does not document PCAP_ERROR_BREAK as a valid return value when the
> pcap_t stands for a live capture.  This requires a straightforward
> separate fix.

That's the pull request at https://github.com/the-tcpdump-group/libpcap/pull/1662

> Another problem is that in commit 6e15abc I missed the subtlety of
> pcap_next_ex() branching into two code paths with different semantics
> of -2: one for a live capture and another for a savefile.

The version before that change had the same problem.

The underlying problem in the man page is that it doesn't note that -2/PCAP_ERROR_BREAK can also be returned... if 
somebody calls pcap_breakloop().

*That* problem was introduced when pcap_breakloop() was added; that was added in

        commit 991d444f7116bef16893826b46f3950f62281507
        Author: Guy Harris <gharris () sonic net>
        Date:   Tue Nov 4 07:05:32 2003 +0000

            Add a "pcap_breakloop()" API to break out of the loop in
            "pcap_dispatch()" and "pcap_loop()".

pcap_next_ex() was added in various commits between 2003-04-09 and 2003-04-10. It came from WinPcap, and returned -2 as 
the EOF indication there.

The reason why -2 was used in WinPcap's pcap_next_ex(), as inferred from a comment in WinPcap (and as explicitly 
*added* to that comment by me, later) was, as noted in my previous message, that a return of 0 means "the timeout fired 
but there were no packets to return" in a live capture, and the WinPcap developers wanted it to be distinguishable from 
"we hit the EOF in a savefile and there are no more packets".

This is a mess, but we can't fix that mess without breaking source and binary compatibility.

> From a code style point of view, a descriptive named constant is better than a bare
> number.  It is debatable whether PCAP_ERROR_BREAK is descriptive enough
> for a savefile context, so if something like PCAP_ERROR_EOF would be
> significantly more readable, let's introduce and use that.  It would
> still be a -2, but in a context where the other -2 is not possible,

There is no such context. A program using pcap_next_ex() could call pcap_breakloop().

> The man page could give a warning
> that for historic reasons the two values are the same, but could
> potentially become different in future.

They'd only be different if we came out with a libpcap 2.x that was source-incompatible and binary-incompatible with 
libpcap 0.x and 1.x. If we did *that*, we might well remove pcap_next() and pcap_next_ex(), possibly replacing them 
with a new API.

So I wouldn't add the "could potentially become different" note.

My inclination is to have the man page say PCAP_ERROR_BREAK is used for an EOF, for historical reasons.

_______________________________________________
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