diff options
author | rpaulo <rpaulo@FreeBSD.org> | 2009-03-21 22:58:08 +0000 |
---|---|---|
committer | rpaulo <rpaulo@FreeBSD.org> | 2009-03-21 22:58:08 +0000 |
commit | 3f19af99adb541ff811a6faaaae340e24ad313c5 (patch) | |
tree | 41d4ee124e8dc2938aa5559c6f422a7b778c807f /contrib/libpcap/pcap_loop.3pcap | |
parent | b0069d00e9ca6c9d90eb18267d0949527c0249e5 (diff) | |
parent | d8d18f6fbdf4f16ae4382f3d0a2d97953edd9b2c (diff) | |
download | FreeBSD-src-3f19af99adb541ff811a6faaaae340e24ad313c5.zip FreeBSD-src-3f19af99adb541ff811a6faaaae340e24ad313c5.tar.gz |
Merge libpcap 1.0.0.
Diffstat (limited to 'contrib/libpcap/pcap_loop.3pcap')
-rw-r--r-- | contrib/libpcap/pcap_loop.3pcap | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/contrib/libpcap/pcap_loop.3pcap b/contrib/libpcap/pcap_loop.3pcap new file mode 100644 index 0000000..8e491d4 --- /dev/null +++ b/contrib/libpcap/pcap_loop.3pcap @@ -0,0 +1,150 @@ +.\" @(#) $Header: /tcpdump/master/libpcap/pcap_loop.3pcap,v 1.1.2.3 2008-04-06 03:21:56 guy Exp $ +.\" +.\" Copyright (c) 1994, 1996, 1997 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that: (1) source code distributions +.\" retain the above copyright notice and this paragraph in its entirety, (2) +.\" distributions including binary code include the above copyright notice and +.\" this paragraph in its entirety in the documentation or other materials +.\" provided with the distribution, and (3) all advertising materials mentioning +.\" features or use of this software display the following acknowledgement: +.\" ``This product includes software developed by the University of California, +.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of +.\" the University nor the names of its contributors may be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.TH PCAP_LOOP 3PCAP "5 April 2008" +.SH NAME +pcap_loop, pcap_dispatch \- process packets from a live capture or savefile +.SH SYNOPSIS +.nf +.ft B +#include <pcap/pcap.h> +.ft +.LP +.ft B +typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h, +.ti +8 + const u_char *bytes); +.ft +.LP +.ft B +int pcap_loop(pcap_t *p, int cnt, +.ti +8 +pcap_handler callback, u_char *user); +int pcap_dispatch(pcap_t *p, int cnt, +.ti +8 +pcap_handler callback, u_char *user); +.ft +.fi +.SH DESCRIPTION +.B pcap_loop() +processes packets from a live capture or ``savefile'' until +.I cnt +packets are processed, the end of the ``savefile'' is +reached when reading from a ``savefile'', +.B pcap_breakloop() +is called, or an error occurs. +It does +.B not +return when live read timeouts occur. +A value of \-1 or 0 for +.I cnt +is equivalent to infinity, so that packets are processed until another +ending condition occurs. +.PP +.B pcap_dispatch() +processes packets from a live capture or ``savefile'' until +.I cnt +packets are processed, the end of the current bufferful of packets is +reached when doing a live capture, the end of the ``savefile'' is +reached when reading from a ``savefile'', +.B pcap_breakloop() +is called, or an error occurs. +Thus, when doing a live capture, +.I cnt +is the maximum number of packets to process before returning, but is not +a minimum number; when reading a live capture, only one +bufferful of packets is read at a time, so fewer than +.I cnt +packets may be processed. A value of \-1 or 0 for +.I cnt +causes all the packets received in one buffer to be processed when +reading a live capture, and causes all the packets in the file to be +processed when reading a ``savefile''. +.PP +.ft B +(In older versions of libpcap, the behavior when +\fIcnt\fP +was 0 was undefined; different platforms and devices behaved +differently, so code that must work with older versions of libpcap +should use \-1, nor 0, as the value of +\fIcnt\fP.) +.ft R +.PP +.I callback +specifies a routine to be called with three arguments: +a +.I u_char +pointer which is passed in the +.I user +argument to +.B pcap_loop() +or +.BR pcap_dispatch() , +a +.I const struct pcap_pkthdr +pointer pointing to the packet time stamp and lengths, and a +.I const u_char +pointer to the first +.B caplen +(as given in the +.I struct pcap_pkthdr +a pointer to which is passed to the callback routine) +bytes of data from the packet. +.SH RETURN VALUE +.B pcap_loop() +returns 0 if +.I cnt +is exhausted, \-1 if an error occurs, or \-2 if the loop terminated due +to a call to +.B pcap_breakloop() +before any packets were processed. +It does +.B not +return when live read 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 +terminated due to a call to +.B pcap_breakloop() +before any packets were processed. +.ft B +If your application uses pcap_breakloop(), +make sure that you explicitly check for \-1 and \-2, rather than just +checking for a return value < 0. +.ft R +.PP +If \-1 is returned, +.B pcap_geterr() +or +.B pcap_perror() +may be called with +.I p +as an argument to fetch or display the error text. +.SH SEE ALSO +pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP) |