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

[Denis Ovsienko <denis () ovsienko info>]

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.

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.  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,
thus appropriately written code would always be able to tell one from
the other, as far as I understand.  The man page could give a warning
that for historic reasons the two values are the same, but could
potentially become different in future.

Yet another problem is that the comments for pcap_next_ex() and
pcap_breakloop() are out of date: neither pcap_read() nor
pcap_read_offline() exist in the current code base.

-- 
    Denis Ovsienko
_______________________________________________
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