Merge branch 'vendor/LIBPCAP'
[dragonfly.git] / contrib / libpcap / pcap_loop.3pcap
CommitLineData
a85e14b0 1.\" @(#) $Header: /tcpdump/master/libpcap/pcap_loop.3pcap,v 1.4 2008-12-25 02:01:32 guy Exp $
de0d3203
PA
2.\"
3.\" Copyright (c) 1994, 1996, 1997
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that: (1) source code distributions
8.\" retain the above copyright notice and this paragraph in its entirety, (2)
9.\" distributions including binary code include the above copyright notice and
10.\" this paragraph in its entirety in the documentation or other materials
11.\" provided with the distribution, and (3) all advertising materials mentioning
12.\" features or use of this software display the following acknowledgement:
13.\" ``This product includes software developed by the University of California,
14.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
15.\" the University nor the names of its contributors may be used to endorse
16.\" or promote products derived from this software without specific prior
17.\" written permission.
18.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
19.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
20.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
21.\"
a85e14b0 22.TH PCAP_LOOP 3PCAP "24 December 2008"
de0d3203
PA
23.SH NAME
24pcap_loop, pcap_dispatch \- process packets from a live capture or savefile
25.SH SYNOPSIS
26.nf
27.ft B
28#include <pcap/pcap.h>
29.ft
30.LP
31.ft B
32typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
33.ti +8
34 const u_char *bytes);
35.ft
36.LP
37.ft B
38int pcap_loop(pcap_t *p, int cnt,
39.ti +8
40pcap_handler callback, u_char *user);
41int pcap_dispatch(pcap_t *p, int cnt,
42.ti +8
43pcap_handler callback, u_char *user);
44.ft
45.fi
46.SH DESCRIPTION
47.B pcap_loop()
48processes packets from a live capture or ``savefile'' until
49.I cnt
50packets are processed, the end of the ``savefile'' is
51reached when reading from a ``savefile'',
52.B pcap_breakloop()
53is called, or an error occurs.
54It does
55.B not
56return when live read timeouts occur.
57A value of \-1 or 0 for
58.I cnt
59is equivalent to infinity, so that packets are processed until another
60ending condition occurs.
61.PP
62.B pcap_dispatch()
63processes packets from a live capture or ``savefile'' until
64.I cnt
65packets are processed, the end of the current bufferful of packets is
66reached when doing a live capture, the end of the ``savefile'' is
67reached when reading from a ``savefile'',
68.B pcap_breakloop()
69is called, or an error occurs.
70Thus, when doing a live capture,
71.I cnt
72is the maximum number of packets to process before returning, but is not
73a minimum number; when reading a live capture, only one
74bufferful of packets is read at a time, so fewer than
75.I cnt
76packets may be processed. A value of \-1 or 0 for
77.I cnt
78causes all the packets received in one buffer to be processed when
79reading a live capture, and causes all the packets in the file to be
80processed when reading a ``savefile''.
81.PP
82.ft B
83(In older versions of libpcap, the behavior when
84\fIcnt\fP
85was 0 was undefined; different platforms and devices behaved
86differently, so code that must work with older versions of libpcap
87should use \-1, nor 0, as the value of
88\fIcnt\fP.)
89.ft R
90.PP
91.I callback
a85e14b0
PA
92specifies a
93.I pcap_handler
94routine to be called with three arguments:
de0d3203
PA
95a
96.I u_char
97pointer which is passed in the
98.I user
99argument to
100.B pcap_loop()
101or
102.BR pcap_dispatch() ,
103a
104.I const struct pcap_pkthdr
105pointer pointing to the packet time stamp and lengths, and a
106.I const u_char
107pointer to the first
108.B caplen
109(as given in the
110.I struct pcap_pkthdr
111a pointer to which is passed to the callback routine)
a85e14b0
PA
112bytes of data from the packet. The
113.I struct pcap_pkthdr
114and the packet data are not to be freed by the callback routine, and are
115not guaranteed to be valid after the callback routine returns; if the
116code needs them to be valid after the callback, it must make a copy of
117them.
de0d3203
PA
118.SH RETURN VALUE
119.B pcap_loop()
120returns 0 if
121.I cnt
122is exhausted, \-1 if an error occurs, or \-2 if the loop terminated due
123to a call to
124.B pcap_breakloop()
125before any packets were processed.
126It does
127.B not
128return when live read timeouts occur; instead, it attempts to read more
129packets.
130.PP
131.B pcap_dispatch()
132returns the number of packets processed on success; this can be 0 if no
133packets were read from a live capture (if, for example, they were
134discarded because they didn't pass the packet filter, or if, on
135platforms that support a read timeout that starts before any packets
136arrive, the timeout expires before any packets arrive, or if the file
137descriptor for the capture device is in non-blocking mode and no packets
138were available to be read) or if no more packets are available in a
139``savefile.'' It returns \-1 if an error occurs or \-2 if the loop
140terminated due to a call to
141.B pcap_breakloop()
142before any packets were processed.
143.ft B
144If your application uses pcap_breakloop(),
145make sure that you explicitly check for \-1 and \-2, rather than just
146checking for a return value < 0.
147.ft R
148.PP
149If \-1 is returned,
150.B pcap_geterr()
151or
152.B pcap_perror()
153may be called with
154.I p
155as an argument to fetch or display the error text.
156.SH SEE ALSO
157pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP)