doc: say what pcap_next_ex() does, clarify issues with other routines.

Document that pcap_next_ex() will, in non-blocking mode, return 0 if no
packets are immediately available.

Document precisely why pcap_loop() and pcap_next() don't behave well in
non-blocking mode.

[skip ci]

diff --git a/pcap_setnonblock.3pcap b/pcap_setnonblock.3pcap
index 96a9131d64189f02319805d5f481aade38f5f38f..a38ca0d7b7ee55f3c699da7d16c60c1720995931 100644 (file)
--- a/pcap_setnonblock.3pcap
+++ b/pcap_setnonblock.3pcap
@@ -49,16 +49,26 @@ is returned and
 .I errbuf
 is filled in with an appropriate error message; otherwise, 0 is
 returned.
 .I errbuf
 is filled in with an appropriate error message; otherwise, 0 is
 returned.

+.PP

 In
 ``non-blocking'' mode, an attempt to read from the capture descriptor
 with
 .BR pcap_dispatch (3PCAP)
 In
 ``non-blocking'' mode, an attempt to read from the capture descriptor
 with
 .BR pcap_dispatch (3PCAP)

+and
+.BR pcap_next_ex (3PCAP)

 will, if no packets are currently available to be read, return 0
 immediately rather than blocking waiting for packets to arrive.
 will, if no packets are currently available to be read, return 0
 immediately rather than blocking waiting for packets to arrive.

+.PP

 .BR pcap_loop (3PCAP)
 .BR pcap_loop (3PCAP)

-and
+will loop forever, consuming CPU time when no packets are currently
+available;
+.BR pacp_dispatch ()
+should be used instead.

 .BR pcap_next (3PCAP)
 .BR pcap_next (3PCAP)

-will not work in ``non-blocking'' mode.
+will return NULL if there are no packets currently available to read;
+this is indistinguishable from an error, so
+.BR pcap_next_ex ()
+should be used instead.

 .PP
 When first activated with
 .BR pcap_activate (3PCAP)
 .PP
 When first activated with
 .BR pcap_activate (3PCAP)