|
Packit |
209cc3 |
.\" Copyright (c) 1994, 1996, 1997
|
|
Packit |
209cc3 |
.\" The Regents of the University of California. All rights reserved.
|
|
Packit |
209cc3 |
.\"
|
|
Packit |
209cc3 |
.\" Redistribution and use in source and binary forms, with or without
|
|
Packit |
209cc3 |
.\" modification, are permitted provided that: (1) source code distributions
|
|
Packit |
209cc3 |
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
|
Packit |
209cc3 |
.\" distributions including binary code include the above copyright notice and
|
|
Packit |
209cc3 |
.\" this paragraph in its entirety in the documentation or other materials
|
|
Packit |
209cc3 |
.\" provided with the distribution, and (3) all advertising materials mentioning
|
|
Packit |
209cc3 |
.\" features or use of this software display the following acknowledgement:
|
|
Packit |
209cc3 |
.\" ``This product includes software developed by the University of California,
|
|
Packit |
209cc3 |
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
|
Packit |
209cc3 |
.\" the University nor the names of its contributors may be used to endorse
|
|
Packit |
209cc3 |
.\" or promote products derived from this software without specific prior
|
|
Packit |
209cc3 |
.\" written permission.
|
|
Packit |
209cc3 |
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
|
Packit |
209cc3 |
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
|
Packit |
209cc3 |
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
Packit |
209cc3 |
.\"
|
|
Packit |
209cc3 |
.TH PCAP_LOOP 3PCAP "25 July 2018"
|
|
Packit |
209cc3 |
.SH NAME
|
|
Packit |
209cc3 |
pcap_loop, pcap_dispatch \- process packets from a live capture or savefile
|
|
Packit |
209cc3 |
.SH SYNOPSIS
|
|
Packit |
209cc3 |
.nf
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
#include <pcap/pcap.h>
|
|
Packit |
209cc3 |
.ft
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
|
|
Packit |
209cc3 |
.ti +8
|
|
Packit |
209cc3 |
const u_char *bytes);
|
|
Packit |
209cc3 |
.ft
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
int pcap_loop(pcap_t *p, int cnt,
|
|
Packit |
209cc3 |
.ti +8
|
|
Packit |
209cc3 |
pcap_handler callback, u_char *user);
|
|
Packit |
209cc3 |
int pcap_dispatch(pcap_t *p, int cnt,
|
|
Packit |
209cc3 |
.ti +8
|
|
Packit |
209cc3 |
pcap_handler callback, u_char *user);
|
|
Packit |
209cc3 |
.ft
|
|
Packit |
209cc3 |
.fi
|
|
Packit |
209cc3 |
.SH DESCRIPTION
|
|
Packit |
209cc3 |
.B pcap_loop()
|
|
Packit |
209cc3 |
processes packets from a live capture or ``savefile'' until
|
|
Packit |
209cc3 |
.I cnt
|
|
Packit |
209cc3 |
packets are processed, the end of the ``savefile'' is
|
|
Packit |
209cc3 |
reached when reading from a ``savefile'',
|
|
Packit |
209cc3 |
.B pcap_breakloop(3PCAP)
|
|
Packit |
209cc3 |
is called, or an error occurs.
|
|
Packit |
209cc3 |
It does
|
|
Packit |
209cc3 |
.B not
|
|
Packit |
209cc3 |
return when live packet buffer timeouts occur.
|
|
Packit |
209cc3 |
A value of \-1 or 0 for
|
|
Packit |
209cc3 |
.I cnt
|
|
Packit |
209cc3 |
is equivalent to infinity, so that packets are processed until another
|
|
Packit |
209cc3 |
ending condition occurs.
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
.B pcap_dispatch()
|
|
Packit |
209cc3 |
processes packets from a live capture or ``savefile'' until
|
|
Packit |
209cc3 |
.I cnt
|
|
Packit |
209cc3 |
packets are processed, the end of the current bufferful of packets is
|
|
Packit |
209cc3 |
reached when doing a live capture, the end of the ``savefile'' is
|
|
Packit |
209cc3 |
reached when reading from a ``savefile'',
|
|
Packit |
209cc3 |
.B pcap_breakloop()
|
|
Packit |
209cc3 |
is called, or an error occurs.
|
|
Packit |
209cc3 |
Thus, when doing a live capture,
|
|
Packit |
209cc3 |
.I cnt
|
|
Packit |
209cc3 |
is the maximum number of packets to process before returning, but is not
|
|
Packit |
209cc3 |
a minimum number; when reading a live capture, only one
|
|
Packit |
209cc3 |
bufferful of packets is read at a time, so fewer than
|
|
Packit |
209cc3 |
.I cnt
|
|
Packit |
209cc3 |
packets may be processed. A value of \-1 or 0 for
|
|
Packit |
209cc3 |
.I cnt
|
|
Packit |
209cc3 |
causes all the packets received in one buffer to be processed when
|
|
Packit |
209cc3 |
reading a live capture, and causes all the packets in the file to be
|
|
Packit |
209cc3 |
processed when reading a ``savefile''.
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
Note that, when doing a live capture on some platforms, if the read
|
|
Packit |
209cc3 |
timeout expires when there are no packets available,
|
|
Packit |
209cc3 |
.B pcap_dispatch()
|
|
Packit |
209cc3 |
will return 0, even when not in non-blocking mode, as there are no
|
|
Packit |
209cc3 |
packets to process. Applications should be prepared for this to happen,
|
|
Packit |
209cc3 |
but must not rely on it happening.
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
(In older versions of libpcap, the behavior when
|
|
Packit |
209cc3 |
\fIcnt\fP
|
|
Packit |
209cc3 |
was 0 was undefined; different platforms and devices behaved
|
|
Packit |
209cc3 |
differently, so code that must work with older versions of libpcap
|
|
Packit |
209cc3 |
should use \-1, not 0, as the value of
|
|
Packit |
209cc3 |
\fIcnt\fP.)
|
|
Packit |
209cc3 |
.ft R
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
.I callback
|
|
Packit |
209cc3 |
specifies a
|
|
Packit |
209cc3 |
.I pcap_handler
|
|
Packit |
209cc3 |
routine to be called with three arguments:
|
|
Packit |
209cc3 |
a
|
|
Packit |
209cc3 |
.I u_char
|
|
Packit |
209cc3 |
pointer which is passed in the
|
|
Packit |
209cc3 |
.I user
|
|
Packit |
209cc3 |
argument to
|
|
Packit |
209cc3 |
.B pcap_loop()
|
|
Packit |
209cc3 |
or
|
|
Packit |
209cc3 |
.BR pcap_dispatch() ,
|
|
Packit |
209cc3 |
a
|
|
Packit |
209cc3 |
.I const struct pcap_pkthdr
|
|
Packit |
209cc3 |
pointer pointing to the packet time stamp and lengths, and a
|
|
Packit |
209cc3 |
.I const u_char
|
|
Packit |
209cc3 |
pointer to the first
|
|
Packit |
209cc3 |
.B caplen
|
|
Packit |
209cc3 |
(as given in the
|
|
Packit |
209cc3 |
.I struct pcap_pkthdr
|
|
Packit |
209cc3 |
a pointer to which is passed to the callback routine)
|
|
Packit |
209cc3 |
bytes of data from the packet. The
|
|
Packit |
209cc3 |
.I struct pcap_pkthdr
|
|
Packit |
209cc3 |
and the packet data are not to be freed by the callback routine, and are
|
|
Packit |
209cc3 |
not guaranteed to be valid after the callback routine returns; if the
|
|
Packit |
209cc3 |
code needs them to be valid after the callback, it must make a copy of
|
|
Packit |
209cc3 |
them.
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
The bytes of data from the packet begin with a link-layer header. The
|
|
Packit |
209cc3 |
format of the link-layer header is indicated by the return value of the
|
|
Packit |
209cc3 |
.B pcap_datalink(3PCAP)
|
|
Packit |
209cc3 |
routine when handed the
|
|
Packit |
209cc3 |
.B pcap_t
|
|
Packit |
209cc3 |
value also passed to
|
|
Packit |
209cc3 |
.B pcap_loop()
|
|
Packit |
209cc3 |
or
|
|
Packit |
209cc3 |
.BR pcap_dispatch() .
|
|
Packit |
209cc3 |
.I https://www.tcpdump.org/linktypes.html
|
|
Packit |
209cc3 |
lists the values
|
|
Packit |
209cc3 |
.B pcap_datalink()
|
|
Packit |
209cc3 |
can return and describes the packet formats that
|
|
Packit |
209cc3 |
correspond to those values. The value it returns will be valid for all
|
|
Packit |
209cc3 |
packets received unless and until
|
|
Packit |
209cc3 |
.B pcap_set_datalink(3PCAP)
|
|
Packit |
209cc3 |
is called; after a successful call to
|
|
Packit |
209cc3 |
.BR pcap_set_datalink() ,
|
|
Packit |
209cc3 |
all subsequent packets will have a link-layer header of the type
|
|
Packit |
209cc3 |
specified by the link-layer header type value passed to
|
|
Packit |
209cc3 |
.BR pcap_set_datalink() .
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
Do
|
|
Packit |
209cc3 |
.B NOT
|
|
Packit |
209cc3 |
assume that the packets for a given capture or ``savefile`` will have
|
|
Packit |
209cc3 |
any given link-layer header type, such as
|
|
Packit |
209cc3 |
.B DLT_EN10MB
|
|
Packit |
209cc3 |
for Ethernet. For example, the "any" device on Linux will have a
|
|
Packit |
209cc3 |
link-layer header type of
|
|
Packit |
209cc3 |
.B DLT_LINUX_SLL
|
|
Packit |
209cc3 |
even if all devices on the system at the time the "any" device is opened
|
|
Packit |
209cc3 |
have some other data link type, such as
|
|
Packit |
209cc3 |
.B DLT_EN10MB
|
|
Packit |
209cc3 |
for Ethernet.
|
|
Packit |
209cc3 |
.SH RETURN VALUE
|
|
Packit |
209cc3 |
.B pcap_loop()
|
|
Packit |
209cc3 |
returns 0 if
|
|
Packit |
209cc3 |
.I cnt
|
|
Packit |
209cc3 |
is exhausted or if, when reading from a ``savefile'', no more packets
|
|
Packit |
209cc3 |
are available. It returns
|
|
Packit |
209cc3 |
.B PCAP_ERROR
|
|
Packit |
209cc3 |
if an error occurs or
|
|
Packit |
209cc3 |
.B PCAP_ERROR_BREAK
|
|
Packit |
209cc3 |
if the loop terminated due to a call to
|
|
Packit |
209cc3 |
.B pcap_breakloop()
|
|
Packit |
209cc3 |
before any packets were processed.
|
|
Packit |
209cc3 |
It does
|
|
Packit |
209cc3 |
.B not
|
|
Packit |
209cc3 |
return when live packet buffer timeouts occur; instead, it attempts to
|
|
Packit |
209cc3 |
read more packets.
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
.B pcap_dispatch()
|
|
Packit |
209cc3 |
returns the number of packets processed on success; this can be 0 if no
|
|
Packit |
209cc3 |
packets were read from a live capture (if, for example, they were
|
|
Packit |
209cc3 |
discarded because they didn't pass the packet filter, or if, on
|
|
Packit |
209cc3 |
platforms that support a packet buffer timeout that starts before any
|
|
Packit |
209cc3 |
packets arrive, the timeout expires before any packets arrive, or if the
|
|
Packit |
209cc3 |
file descriptor for the capture device is in non-blocking mode and no
|
|
Packit |
209cc3 |
packets were available to be read) or if no more packets are available
|
|
Packit |
209cc3 |
in a ``savefile.'' It returns
|
|
Packit |
209cc3 |
.B PCAP_ERROR
|
|
Packit |
209cc3 |
if an error occurs or
|
|
Packit |
209cc3 |
.B PCAP_ERROR_BREAK
|
|
Packit |
209cc3 |
if the loop terminated due to a call to
|
|
Packit |
209cc3 |
.B pcap_breakloop()
|
|
Packit |
209cc3 |
before any packets were processed.
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
If your application uses pcap_breakloop(),
|
|
Packit |
209cc3 |
make sure that you explicitly check for PCAP_ERROR and PCAP_ERROR_BREAK,
|
|
Packit |
209cc3 |
rather than just checking for a return value < 0.
|
|
Packit |
209cc3 |
.ft R
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
If
|
|
Packit |
209cc3 |
.B PCAP_ERROR
|
|
Packit |
209cc3 |
is returned,
|
|
Packit |
209cc3 |
.B pcap_geterr(3PCAP)
|
|
Packit |
209cc3 |
or
|
|
Packit |
209cc3 |
.B pcap_perror(3PCAP)
|
|
Packit |
209cc3 |
may be called with
|
|
Packit |
209cc3 |
.I p
|
|
Packit |
209cc3 |
as an argument to fetch or display the error text.
|
|
Packit |
209cc3 |
.SH SEE ALSO
|
|
Packit |
209cc3 |
pcap(3PCAP)
|