2 * Do the low-level work of a capture
6 * Wireshark - Network traffic analyzer
7 * By Gerald Combs <gerald@wireshark.org>
8 * Copyright 1998 Gerald Combs
10 * This program is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU General Public License
12 * as published by the Free Software Foundation; either version 2
13 * of the License, or (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, write to the Free Software
22 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 * Do the low-level work of a capture.
32 #ifndef __CAPTURE_LOOP_H__
33 #define __CAPTURE_LOOP_H__
36 * Get information about libpcap format from "wiretap/libpcap.h".
37 * XXX - can we just use pcap_open_offline() to read the pipe?
39 #include "wiretap/libpcap.h"
41 /** Do the low-level work of a capture.
42 * Returns TRUE if it succeeds, FALSE otherwise. */
43 extern int capture_loop_start(capture_options *capture_opts, gboolean *stats_known, struct pcap_stat *stats);
45 /** Stop a low-level capture (stops the capture child). */
46 extern void capture_loop_stop(void);
49 /*** the following is internal only (should be moved to capture_loop_int.h) ***/
51 #if !defined (__linux__)
52 #ifndef HAVE_PCAP_BREAKLOOP
54 * We don't have pcap_breakloop(), which is the only way to ensure that
55 * pcap_dispatch(), pcap_loop(), or even pcap_next() or pcap_next_ex()
56 * won't, if the call to read the next packet or batch of packets is
57 * is interrupted by a signal on UN*X, just go back and try again to
60 * On UN*X, we catch SIGUSR1 as a "stop capturing" signal, and, in
61 * the signal handler, set a flag to stop capturing; however, without
62 * a guarantee of that sort, we can't guarantee that we'll stop capturing
63 * if the read will be retried and won't time out if no packets arrive.
65 * Therefore, on at least some platforms, we work around the lack of
66 * pcap_breakloop() by doing a select() on the pcap_t's file descriptor
67 * to wait for packets to arrive, so that we're probably going to be
68 * blocked in the select() when the signal arrives, and can just bail
69 * out of the loop at that point.
71 * However, we don't want to that on BSD (because "select()" doesn't work
72 * correctly on BPF devices on at least some releases of some flavors of
73 * BSD), and we don't want to do it on Windows (because "select()" is
74 * something for sockets, not for arbitrary handles). (Note that "Windows"
75 * here includes Cygwin; even in its pretend-it's-UNIX environment, we're
76 * using WinPcap, not a UNIX libpcap.)
78 * Fortunately, we don't need to do it on BSD, because the libpcap timeout
79 * on BSD times out even if no packets have arrived, so we'll eventually
80 * exit pcap_dispatch() with an indication that no packets have arrived,
81 * and will break out of the capture loop at that point.
83 * On Windows, we can't send a SIGUSR1 to stop capturing, so none of this
84 * applies in any case.
86 * XXX - the various BSDs appear to define BSD in <sys/param.h>; we don't
87 * want to include it if it's not present on this platform, however.
89 # if !defined(__FreeBSD__) && !defined(__NetBSD__) && !defined(__OpenBSD__) && \
90 !defined(__bsdi__) && !defined(__APPLE__) && !defined(_WIN32) && \
92 # define MUST_DO_SELECT
93 # endif /* avoid select */
94 #endif /* HAVE_PCAP_BREAKLOOP */
96 /* whatever the deal with pcap_breakloop, linux doesn't support timeouts
97 * in pcap_dispatch(); on the other hand, select() works just fine there.
98 * Hence we use a select for that come what may.
100 #define MUST_DO_SELECT
103 typedef void (*capture_packet_cb_fct)(u_char *, const struct pcap_pkthdr *, const u_char *);
105 /** init the capture filter */
108 INITFILTER_BAD_FILTER,
109 INITFILTER_OTHER_ERROR
110 } initfilter_status_t;
113 * Routines called by the capture loop code to report things.
116 /** Report a new capture file having been opened. */
118 report_new_capture_file(const char *filename);
120 /** Report a number of new packets captured. */
122 report_packet_count(int packet_count);
124 /** Report the packet drops once the capture finishes. */
126 report_packet_drops(int drops);
128 /** Report an error in the capture. */
130 report_capture_error(const char *error_msg, const char *secondary_error_msg);
132 /** Report an error with a capture filter. */
134 report_cfilter_error(const char *cfilter, const char *errmsg);
137 #endif /* capture_loop.h */