freebsd-nq/contrib/libpcap/pcap_loop.3pcap

207 lines
6.6 KiB
Plaintext
Raw Normal View History

2009-03-21 20:43:56 +00:00
.\" 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.
.\"
2019-10-06 04:26:37 +00:00
.TH PCAP_LOOP 3PCAP "25 July 2018"
2009-03-21 20:43:56 +00:00
.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'',
2019-10-06 04:26:37 +00:00
.B pcap_breakloop(3PCAP)
2009-03-21 20:43:56 +00:00
is called, or an error occurs.
It does
.B not
return when live packet buffer timeouts occur.
2009-03-21 20:43:56 +00:00
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
2017-02-12 07:04:44 +00:00
Note that, when doing a live capture on some platforms, if the read
timeout expires when there are no packets available,
.B pcap_dispatch()
will return 0, even when not in non-blocking mode, as there are no
packets to process. Applications should be prepared for this to happen,
but must not rely on it happening.
.PP
2009-03-21 20:43:56 +00:00
.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
2013-05-30 06:41:26 +00:00
should use \-1, not 0, as the value of
2009-03-21 20:43:56 +00:00
\fIcnt\fP.)
.ft R
.PP
.I callback
Update libpcap to 1.1.1. Changes: Thu. April 1, 2010. guy@alum.mit.edu. Summary for 1.1.1 libpcap release Update CHANGES to reflect more of the changes in 1.1.0. Fix build on RHEL5. Fix shared library build on AIX. Thu. March 11, 2010. ken@netfunctional.ca/guy@alum.mit.edu. Summary for 1.1.0 libpcap release Add SocketCAN capture support Add Myricom SNF API support Update Endace DAG and ERF support Add support for shared libraries on Solaris, HP-UX, and AIX Build, install, and un-install shared libraries by default; don't build/install shared libraries on platforms we don't support Fix building from a directory other than the source directory Fix compiler warnings and builds on some platforms Update config.guess and config.sub Support monitor mode on mac80211 devices on Linux Fix USB memory-mapped capturing on Linux; it requires a new DLT_ value On Linux, scan /sys/class/net for devices if we have it; scan it, or /proc/net/dev if we don't have /sys/class/net, even if we have getifaddrs(), as it'll find interfaces with no addresses Add limited support for reading pcap-ng files Fix BPF driver-loading error handling on AIX Support getting the full-length interface description on FreeBSD In the lexical analyzer, free up any addrinfo structure we got back from getaddrinfo(). Add support for BPF and libdlpi in OpenSolaris (and SXCE) Hyphenate "link-layer" everywhere Add /sys/kernel/debug/usb/usbmon to the list of usbmon locations In pcap_read_linux_mmap(), if there are no frames available, call poll() even if we're in non-blocking mode, so we pick up errors, and check for the errors in question. Note that poll() works on BPF devices is Snow Leopard If an ENXIO or ENETDOWN is received, it may mean the device has gone away. Deal with it. For BPF, raise the default capture buffer size to from 32k to 512k Support ps_ifdrop on Linux Added a bunch of #ifdef directives to make wpcap.dll (WinPcap) compile under cygwin. Changes to Linux mmapped captures. Fix bug where create_ring would fail for particular snaplen and buffer size combinations Update pcap-config so that it handles libpcap requiring additional libraries Add workaround for threadsafeness on Windows Add missing mapping for DLT_ENC <-> LINKTYPE_ENC DLT: Add DLT_CAN_SOCKETCAN DLT: Add Solaris ipnet Don't check for DLT_IPNET if it's not defined Add link-layer types for Fibre Channel FC-2 Add link-layer types for Wireless HART Add link-layer types for AOS Add link-layer types for DECT Autoconf fixes (AIX, HP-UX, OSF/1, Tru64 cleanups) Install headers unconditionally, and include vlan.h/bluetooth.h if enabled Autoconf fixes+cleanup Support enabling/disabling bluetooth (--{en,dis}able-bluetooth) Support disabling SITA support (--without-sita) Return -1 on failure to create packet ring (if supported but creation failed) Fix handling of 'any' device, so that it can be opened, and no longer attempt to open it in Monitor mode Add support for snapshot length for USB Memory-Mapped Interface Fix configure and build on recent Linux kernels Fix memory-mapped Linux capture to support pcap_next() and pcap_next_ex() Fixes for Linux USB capture DLT: Add DLT_LINUX_EVDEV DLT: Add DLT_GSMTAP_UM DLT: Add DLT_GSMTAP_ABIS
2010-10-28 16:22:13 +00:00
specifies a
.I pcap_handler
routine to be called with three arguments:
2009-03-21 20:43:56 +00:00
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. The
.I struct pcap_pkthdr
and the packet data are not to be freed by the callback routine, and are
not guaranteed to be valid after the callback routine returns; if the
code needs them to be valid after the callback, it must make a copy of
them.
2015-01-06 18:58:31 +00:00
.PP
The bytes of data from the packet begin with a link-layer header. The
format of the link-layer header is indicated by the return value of the
2019-10-06 04:26:37 +00:00
.B pcap_datalink(3PCAP)
2015-01-06 18:58:31 +00:00
routine when handed the
.B pcap_t
value also passed to
.B pcap_loop()
or
.BR pcap_dispatch() .
2019-10-06 04:26:37 +00:00
.I https://www.tcpdump.org/linktypes.html
2015-01-06 18:58:31 +00:00
lists the values
.B pcap_datalink()
can return and describes the packet formats that
correspond to those values. The value it returns will be valid for all
packets received unless and until
2019-10-06 04:26:37 +00:00
.B pcap_set_datalink(3PCAP)
2015-01-06 18:58:31 +00:00
is called; after a successful call to
.BR pcap_set_datalink() ,
all subsequent packets will have a link-layer header of the type
specified by the link-layer header type value passed to
.BR pcap_set_datalink() .
.PP
Do
.B NOT
assume that the packets for a given capture or ``savefile`` will have
any given link-layer header type, such as
.B DLT_EN10MB
for Ethernet. For example, the "any" device on Linux will have a
link-layer header type of
.B DLT_LINUX_SLL
even if all devices on the system at the time the "any" device is opened
have some other data link type, such as
.B DLT_EN10MB
for Ethernet.
2009-03-21 20:43:56 +00:00
.SH RETURN VALUE
.B pcap_loop()
returns 0 if
.I cnt
2013-05-30 06:41:26 +00:00
is exhausted or if, when reading from a ``savefile'', no more packets
2019-10-06 04:26:37 +00:00
are available. It returns
.B PCAP_ERROR
if an error occurs or
.B PCAP_ERROR_BREAK
if the loop terminated due to a call to
2009-03-21 20:43:56 +00:00
.B pcap_breakloop()
before any packets were processed.
It does
.B not
return when live packet buffer timeouts occur; instead, it attempts to
read more packets.
2009-03-21 20:43:56 +00:00
.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 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
2019-10-06 04:26:37 +00:00
in a ``savefile.'' It returns
.B PCAP_ERROR
if an error occurs or
.B PCAP_ERROR_BREAK
if the loop terminated due to a call to
2009-03-21 20:43:56 +00:00
.B pcap_breakloop()
before any packets were processed.
.ft B
If your application uses pcap_breakloop(),
2019-10-06 04:26:37 +00:00
make sure that you explicitly check for PCAP_ERROR and PCAP_ERROR_BREAK,
rather than just checking for a return value < 0.
2009-03-21 20:43:56 +00:00
.ft R
.PP
2019-10-06 04:26:37 +00:00
If
.B PCAP_ERROR
is returned,
.B pcap_geterr(3PCAP)
2009-03-21 20:43:56 +00:00
or
2019-10-06 04:26:37 +00:00
.B pcap_perror(3PCAP)
2009-03-21 20:43:56 +00:00
may be called with
.I p
as an argument to fetch or display the error text.
.SH SEE ALSO
2019-10-06 04:26:37 +00:00
pcap(3PCAP)