diff options
| -rw-r--r-- | pcap-rpcap.c | 2 | ||||
| -rw-r--r-- | pcap-win32.c | 3 | ||||
| -rw-r--r-- | pcap.3pcap.in | 64 | ||||
| -rw-r--r-- | pcap_get_selectable_fd.3pcap | 10 | ||||
| -rw-r--r-- | pcap_loop.3pcap | 18 | ||||
| -rw-r--r-- | pcap_next_ex.3pcap | 27 | ||||
| -rw-r--r-- | pcap_open_live.3pcap | 6 | ||||
| -rw-r--r-- | pcap_set_timeout.3pcap | 14 |
8 files changed, 74 insertions, 70 deletions
diff --git a/pcap-rpcap.c b/pcap-rpcap.c index 5add0573..d8526c4c 100644 --- a/pcap-rpcap.c +++ b/pcap-rpcap.c @@ -219,7 +219,7 @@ static int pcap_read_nocb_remote(pcap_t *p, struct pcap_pkthdr **pkt_header, u_c md = (struct pcap_md *) ((u_char*)p->priv + sizeof(struct pcap_win)); /* - * Define the read timeout, to be used in the select() + * Define the packet buffer timeout, to be used in the select() * 'timeout', in pcap_t, is in milliseconds; we have to convert it into sec and microsec */ tv.tv_sec = p->opt.timeout / 1000; diff --git a/pcap-win32.c b/pcap-win32.c index aa24a425..2f658e4f 100644 --- a/pcap-win32.c +++ b/pcap-win32.c @@ -1321,7 +1321,8 @@ pcap_setnonblock_win32(pcap_t *p, int nonblock, char *errbuf) if (nonblock) { /* - * Set the read timeout to -1 for non-blocking mode. + * Set the packet buffer timeout to -1 for non-blocking + * mode. */ newtimeout = -1; } else { diff --git a/pcap.3pcap.in b/pcap.3pcap.in index dd577983..6dcac203 100644 --- a/pcap.3pcap.in +++ b/pcap.3pcap.in @@ -17,7 +17,7 @@ .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.TH PCAP 3PCAP "8 March 2015" +.TH PCAP 3PCAP "20 January 2017" .SH NAME pcap \- Packet Capture library .SH SYNOPSIS @@ -150,45 +150,44 @@ and .BR pcap_can_set_rfmon () can be used to determine whether an adapter can be put into monitor mode. -.IP "read timeout" +.IP "packet buffer timeout" If, when capturing, packets are delivered as soon as they arrive, the application capturing the packets will be woken up for each packet as it arrives, and might have to make one or more calls to the operating system to fetch each packet. .IP If, instead, packets are not delivered as soon as they arrive, but are -delivered after a short delay (called a "read timeout"), more than one -packet can be accumulated before the packets are delivered, so that a -single wakeup would be done for multiple packets, and each set of calls -made to the operating system would supply multiple packets, rather than -a single packet. This reduces the per-packet CPU overhead if packets -are arriving at a high rate, increasing the number of packets per second -that can be captured. +delivered after a short delay (called a "packet buffer timeout"), more +than one packet can be accumulated before the packets are delivered, so +that a single wakeup would be done for multiple packets, and each set of +calls made to the operating system would supply multiple packets, rather +than a single packet. This reduces the per-packet CPU overhead if +packets are arriving at a high rate, increasing the number of packets +per second that can be captured. .IP -The read timeout is required so that an application won't wait for the -operating system's capture buffer to fill up before packets are +The packet buffer timeout is required so that an application won't wait +for the operating system's capture buffer to fill up before packets are delivered; if packets are arriving slowly, that wait could take an arbitrarily long period of time. .IP -Not all platforms support a read timeout; on platforms that -don't, the read timeout is ignored. A zero value for the timeout, -on platforms that support a read timeout, -will cause a read to wait forever to allow enough packets to -arrive, with no timeout. +Not all platforms support a packet buffer timeout; on platforms that +don't, the packet buffer timeout is ignored. A zero value for the +timeout, on platforms that support a packet buffer timeout, will cause a +read to wait forever to allow enough packets to arrive, with no timeout. .IP .BR NOTE : -the read timeout cannot be used to cause calls that read +the packet buffer timeout cannot be used to cause calls that read packets to return within a limited period of time, because, on some -platforms, the read timeout isn't supported, and, on other platforms, -the timer doesn't start until at least one packet arrives. This means -that the read timeout should +platforms, the packet buffer timeout isn't supported, and, on other +platforms, the timer doesn't start until at least one packet arrives. +This means that the packet buffer timeout should .B NOT be used, for example, in an interactive application to allow the packet capture loop to ``poll'' for user input periodically, as there's no guarantee that a call reading packets will return after the timeout expires even if no packets have arrived. .IP -The read timeout is set with +The packet buffer timeout is set with .BR pcap_set_timeout (). .IP "buffer size" Packets that arrive for a capture are stored in a buffer, so that they @@ -406,7 +405,7 @@ determine whether monitor mode can be set for a for live capture .TP .BR pcap_set_timeout (3PCAP) -set read timeout for a not-yet-activated +set packet buffer timeout for a not-yet-activated .B pcap_t for live capture .TP @@ -600,12 +599,13 @@ and will, if no packets are currently available to be read, block waiting for packets to become available. On some, but .I not -all, platforms, if a read timeout was specified, the wait will terminate -after the read timeout expires; applications should be prepared for -this, as it happens on some platforms, but should not rely on it, as it -does not happen on other platforms. Note that the wait might, or might -not, terminate even if no packets are available; applications should be -prepared for this to happen, but must not rely on it happening. +all, platforms, if a packet buffer timeout was specified, the wait will +terminate after the packet buffer timeout expires; applications should +be prepared for this, as it happens on some platforms, but should not +rely on it, as it does not happen on other platforms. Note that the +wait might, or might not, terminate even if no packets are available; +applications should be prepared for this to happen, but must not rely on +it happening. .PP A handle can be put into ``non-blocking mode'', so that those routines will, rather than blocking, return an indication that no packets are @@ -633,12 +633,12 @@ descriptor; the documentation for .BR pcap_get_selectable_fd () gives details. Note that, just as an attempt to read packets from a .B pcap_t -may not return any packets if the read timeout expires, a +may not return any packets if the packet buffer timeout expires, a .BR select (), .BR poll (), -or other such call may, if the read timeout expires, indicate that a -descriptor is ready to read even if there are no packets available to -read. +or other such call may, if the packet buffer timeout expires, indicate +that a descriptor is ready to read even if there are no packets +available to read. .TP .B Routines .RS diff --git a/pcap_get_selectable_fd.3pcap b/pcap_get_selectable_fd.3pcap index 86b0c268..aa457a23 100644 --- a/pcap_get_selectable_fd.3pcap +++ b/pcap_get_selectable_fd.3pcap @@ -17,7 +17,7 @@ .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.TH PCAP_GET_SELECTABLE_FD 3PCAP "18 October 2014" +.TH PCAP_GET_SELECTABLE_FD 3PCAP "20 January 2017" .SH NAME pcap_get_selectable_fd \- get a file descriptor on which a select() can be done for a live capture @@ -55,8 +55,8 @@ or DAG devices), so \-1 is returned for those devices. .PP Note that a descriptor on which a read can be done without blocking may, -on some platforms, not have any packets to read if the read timeout has -expired. A call to +on some platforms, not have any packets to read if the packet buffer +timeout has expired. A call to .B pcap_dispatch() will return 0 in this case, but will not block. .PP @@ -81,7 +81,7 @@ being FreeBSD 4.3 and 4.4), but a simple or .B poll() will not indicate that the descriptor is readable until a full buffer's -worth of packets is received, even if the read timeout expires before +worth of packets is received, even if the packet timeout expires before then. To work around this, an application that uses .B select() or @@ -92,7 +92,7 @@ in non-blocking mode, and must arrange that the .B select() or .B poll() -have a timeout less than or equal to the read timeout, +have a timeout less than or equal to the packet buffer timeout, and must try to read packets after that timeout expires, regardless of whether .B select() diff --git a/pcap_loop.3pcap b/pcap_loop.3pcap index 0eaf6e5e..15ad4101 100644 --- a/pcap_loop.3pcap +++ b/pcap_loop.3pcap @@ -17,7 +17,7 @@ .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.TH PCAP_LOOP 3PCAP "18 October 2014" +.TH PCAP_LOOP 3PCAP "20 January 2017" .SH NAME pcap_loop, pcap_dispatch \- process packets from a live capture or savefile .SH SYNOPSIS @@ -51,7 +51,7 @@ reached when reading from a ``savefile'', is called, or an error occurs. It does .B not -return when live read timeouts occur. +return when live packet buffer timeouts occur. A value of \-1 or 0 for .I cnt is equivalent to infinity, so that packets are processed until another @@ -166,18 +166,18 @@ terminated due to a call to before any packets were processed. It does .B not -return when live read timeouts occur; instead, it attempts to read more -packets. +return when live packet buffer timeouts occur; instead, it attempts to +read more packets. .PP .B pcap_dispatch() returns the number of packets processed on success; this can be 0 if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on -platforms that support a read timeout that starts before any packets -arrive, the timeout expires before any packets arrive, or if the file -descriptor for the capture device is in non-blocking mode and no packets -were available to be read) or if no more packets are available in a -``savefile.'' It returns \-1 if an error occurs or \-2 if the loop +platforms that support a packet buffer timeout that starts before any +packets arrive, the timeout expires before any packets arrive, or if the +file descriptor for the capture device is in non-blocking mode and no +packets were available to be read) or if no more packets are available +in a ``savefile.'' It returns \-1 if an error occurs or \-2 if the loop terminated due to a call to .B pcap_breakloop() before any packets were processed. diff --git a/pcap_next_ex.3pcap b/pcap_next_ex.3pcap index d69e7283..f975ccfd 100644 --- a/pcap_next_ex.3pcap +++ b/pcap_next_ex.3pcap @@ -17,7 +17,7 @@ .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.TH PCAP_NEXT_EX 3PCAP "7 April 2014" +.TH PCAP_NEXT_EX 3PCAP "20 January 2017" .SH NAME pcap_next_ex, pcap_next \- read the next packet from a pcap_t .SH SYNOPSIS @@ -112,12 +112,11 @@ have some other data link type, such as for Ethernet. .SH RETURN VALUE .B pcap_next_ex() -returns 1 if the packet was read without problems, 0 -if packets are being read from a live capture and the timeout expired, -\-1 if an error occurred while reading the packet, and \-2 if -packets are being read from a ``savefile'' and there are no more -packets to read from the savefile. -If \-1 is returned, +returns 1 if the packet was read without problems, 0 if packets are +being read from a live capture and the packet buffer timeout expired, +\-1 if an error occurred while reading the packet, and \-2 if packets +are being read from a ``savefile'' and there are no more packets to read +from the savefile. If \-1 is returned, .B pcap_geterr() or .B pcap_perror() @@ -128,14 +127,14 @@ as an argument to fetch or display the error text. .B pcap_next() returns a pointer to the packet data on success, and returns .B NULL -if an error occurred, or if no packets were read from a live -capture (if, for example, they were discarded because they didn't pass -the packet filter, or if, on platforms that support a read timeout that -starts before any packets arrive, the timeout expires before any packets -arrive, or if the file descriptor for the capture device is in +if an error occurred, or if no packets were read from a live capture +(if, for example, they were discarded because they didn't pass the +packet filter, or if, on platforms that support a packet buffer timeout +that starts before any packets arrive, the timeout expires before any +packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read), or if no -more packets are available in a ``savefile.'' Unfortunately, there is -no way to determine whether an error occurred or not. +more packets are available in a ``savefile.'' Unfortunately, there is no +way to determine whether an error occurred or not. .SH SEE ALSO pcap(3PCAP), pcap_geterr(3PCAP), pcap_dispatch(3PCAP), pcap_datalink(3PCAP) diff --git a/pcap_open_live.3pcap b/pcap_open_live.3pcap index 8c5d4746..ce45c284 100644 --- a/pcap_open_live.3pcap +++ b/pcap_open_live.3pcap @@ -17,7 +17,7 @@ .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.TH PCAP_OPEN_LIVE 3PCAP "3 January 2014" +.TH PCAP_OPEN_LIVE 3PCAP "20 January 2017" .SH NAME pcap_open_live \- open a device for capturing .SH SYNOPSIS @@ -56,7 +56,9 @@ specifies the snapshot length to be set on the handle. specifies if the interface is to be put into promiscuous mode. .PP .I to_ms -specifies the read timeout in milliseconds. +specifies the packet buffer timeout in milliseconds. (See +.BR pcap (3PCAP) +for an explanation of the packet buffer timeout.) .SH RETURN VALUE .B pcap_open_live() returns a diff --git a/pcap_set_timeout.3pcap b/pcap_set_timeout.3pcap index a89327f2..dd718483 100644 --- a/pcap_set_timeout.3pcap +++ b/pcap_set_timeout.3pcap @@ -17,10 +17,10 @@ .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.TH PCAP_SET_TIMEOUT 3PCAP "1 December 2015" +.TH PCAP_SET_TIMEOUT 3PCAP "20 January 2017" .SH NAME -pcap_set_timeout \- set the read timeout for a not-yet-activated -capture handle +pcap_set_timeout \- set the packet buffer timeout for a +not-yet-activated capture handle .SH SYNOPSIS .nf .ft B @@ -32,10 +32,12 @@ int pcap_set_timeout(pcap_t *p, int to_ms); .fi .SH DESCRIPTION .B pcap_set_timeout() -sets the read timeout that will be used on a capture handle when -the handle is activated to +sets the packet buffer timeout that will be used on a capture handle +when the handle is activated to .IR to_ms , -which is in units of milliseconds. +which is in units of milliseconds. (See +.BR pcap (3PCAP) +for an explanation of the packet buffer timeout.) .LP The behavior, if the timeout isn't specified, is undefined. We recommend always setting the timeout to a non-zero value unless |