Wireshark  4.3.0
The Wireshark network protocol analyzer
/builds/wireshark/wireshark/capture_opts.h
Go to the documentation of this file.
1 /* capture_opts.h
2  * Capture options (all parameters needed to do the actual capture)
3  *
4  * Wireshark - Network traffic analyzer
5  * By Gerald Combs <gerald@wireshark.org>
6  * Copyright 1998 Gerald Combs
7  *
8  * SPDX-License-Identifier: GPL-2.0-or-later
9  */
10 
11 
18 #ifndef __CAPTURE_OPTS_H__
19 #define __CAPTURE_OPTS_H__
20 
21 #include <sys/types.h> /* for gid_t */
22 
23 #include <capture/capture_ifinfo.h>
24 #include "ringbuffer.h"
25 #include <wsutil/wslog.h>
26 #include <wsutil/filter_files.h>
27 
28 #ifdef _WIN32
29 #include <windows.h>
30 #endif
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif /* __cplusplus */
35 
36 /*
37  * Long options.
38  * We do not currently have long options corresponding to all short
39  * options; we should probably pick appropriate option names for them.
40  *
41  * NOTE:
42  * for tshark, we're using a leading - in the optstring to prevent getopt()
43  * from permuting the argv[] entries, in this case, unknown argv[] entries
44  * will be returned as parameters to a dummy-option 1.
45  * In short: we must not use 1 here, which is another reason to use
46  * values outside the range of ASCII graphic characters.
47  */
48 #define LONGOPT_LIST_TSTAMP_TYPES LONGOPT_BASE_CAPTURE+1
49 #define LONGOPT_SET_TSTAMP_TYPE LONGOPT_BASE_CAPTURE+2
50 #define LONGOPT_COMPRESS_TYPE LONGOPT_BASE_CAPTURE+3
51 #define LONGOPT_CAPTURE_TMPDIR LONGOPT_BASE_CAPTURE+4
52 #define LONGOPT_UPDATE_INTERVAL LONGOPT_BASE_CAPTURE+5
53 
54 /*
55  * Options for capturing common to all capturing programs.
56  */
57 #ifdef HAVE_PCAP_REMOTE
58 #define OPTSTRING_A "A:"
59 #else
60 #define OPTSTRING_A
61 #endif
62 
63 #ifdef CAN_SET_CAPTURE_BUFFER_SIZE
64 #define LONGOPT_BUFFER_SIZE \
65  {"buffer-size", ws_required_argument, NULL, 'B'},
66 #define OPTSTRING_B "B:"
67 #else
68 #define LONGOPT_BUFFER_SIZE
69 #define OPTSTRING_B
70 #endif
71 
72 #ifdef HAVE_PCAP_CREATE
73 #define LONGOPT_MONITOR_MODE {"monitor-mode", ws_no_argument, NULL, 'I'},
74 #define OPTSTRING_I "I"
75 #else
76 #define LONGOPT_MONITOR_MODE
77 #define OPTSTRING_I
78 #endif
79 
80 #define LONGOPT_CAPTURE_COMMON \
81  {"autostop", ws_required_argument, NULL, 'a'}, \
82  {"ring-buffer", ws_required_argument, NULL, 'b'}, \
83  LONGOPT_BUFFER_SIZE \
84  {"list-interfaces", ws_no_argument, NULL, 'D'}, \
85  {"interface", ws_required_argument, NULL, 'i'}, \
86  LONGOPT_MONITOR_MODE \
87  {"list-data-link-types", ws_no_argument, NULL, 'L'}, \
88  {"no-promiscuous-mode", ws_no_argument, NULL, 'p'}, \
89  {"snapshot-length", ws_required_argument, NULL, 's'}, \
90  {"linktype", ws_required_argument, NULL, 'y'}, \
91  {"list-time-stamp-types", ws_no_argument, NULL, LONGOPT_LIST_TSTAMP_TYPES}, \
92  {"time-stamp-type", ws_required_argument, NULL, LONGOPT_SET_TSTAMP_TYPE}, \
93  {"compress-type", ws_required_argument, NULL, LONGOPT_COMPRESS_TYPE}, \
94  {"temp-dir", ws_required_argument, NULL, LONGOPT_CAPTURE_TMPDIR},\
95  {"update-interval", ws_required_argument, NULL, LONGOPT_UPDATE_INTERVAL},
96 
97 
98 #define OPTSTRING_CAPTURE_COMMON \
99  "a:" OPTSTRING_A "b:" OPTSTRING_B "c:Df:F:i:" OPTSTRING_I "Lps:y:"
100 
101 #ifdef HAVE_PCAP_REMOTE
102 /* Type of capture source */
103 typedef enum {
104  CAPTURE_IFLOCAL,
105  CAPTURE_IFREMOTE
106 } capture_source;
107 
108 /* Type of RPCAPD Authentication */
109 typedef enum {
110  CAPTURE_AUTH_NULL,
111  CAPTURE_AUTH_PWD
112 } capture_auth;
113 #endif
114 #ifdef HAVE_PCAP_SETSAMPLING
119 typedef enum {
120  CAPTURE_SAMP_NONE,
121  CAPTURE_SAMP_BY_COUNT,
123  CAPTURE_SAMP_BY_TIMER
126 } capture_sampling;
127 #endif
128 
129 #ifdef HAVE_PCAP_REMOTE
130 struct remote_host_info {
131  gchar *remote_host;
132  gchar *remote_port;
133  capture_auth auth_type;
134  gchar *auth_username;
135  gchar *auth_password;
136  gboolean datatx_udp;
137  gboolean nocap_rpcap;
138  gboolean nocap_local;
139 };
140 
141 struct remote_host {
142  gchar *r_host;
143  gchar *remote_port;
144  capture_auth auth_type;
145  gchar *auth_username;
146  gchar *auth_password;
147 };
148 
149 typedef struct remote_options_tag {
150  capture_source src_type;
151  struct remote_host_info remote_host_opts;
152 #ifdef HAVE_PCAP_SETSAMPLING
153  capture_sampling sampling_method;
154  int sampling_param;
155 #endif
156 } remote_options;
157 #endif /* HAVE_PCAP_REMOTE */
158 
159 typedef struct interface_tag {
160  gchar *name;
161  gchar *display_name;
162  gchar *addresses;
163  gint no_addresses;
164  gchar *cfilter;
165  GList *links;
166  gint active_dlt;
167  bool pmode;
168  bool has_snaplen;
169  int snaplen;
170  gboolean local;
171 #ifdef CAN_SET_CAPTURE_BUFFER_SIZE
172  gint buffer;
173 #endif
174 #ifdef HAVE_PCAP_CREATE
175  gboolean monitor_mode_enabled;
176  gboolean monitor_mode_supported;
177 #endif
178 #ifdef HAVE_PCAP_REMOTE
179  remote_options remote_opts;
180 #endif
181  guint32 last_packets;
182  guint32 packet_diff;
184  gboolean selected;
185  gboolean hidden;
186  /* External capture cached data */
187  GHashTable *external_cap_args_settings;
188  gchar *timestamp_type;
189 } interface_t;
190 
191 typedef struct link_row_tag {
192  gchar *name;
193  gint dlt;
194 } link_row;
195 
196 typedef struct interface_options_tag {
197  gchar *name; /* the name of the interface supplied to libpcap/WinPcap/Npcap to specify the interface */
198  gchar *descr; /* a more user-friendly description of the interface; may be NULL if none */
199  gchar *hardware; /* description of the hardware */
200  gchar *display_name; /* the name displayed in the console and title bar */
201  gchar *ifname; /* if not null, name to use instead of the interface naem in IDBs */
202  gchar *cfilter;
203  gboolean has_snaplen;
204  int snaplen;
205  int linktype;
206  gboolean promisc_mode;
207  interface_type if_type;
208  gchar *extcap;
209  gchar *extcap_fifo;
210  GHashTable *extcap_args;
211  GPid extcap_pid; /* pid of running process or WS_INVALID_PID */
212  gpointer extcap_pipedata;
213  GString *extcap_stderr;
214  guint extcap_stdout_watch;
215  guint extcap_stderr_watch;
216 #ifdef _WIN32
217  HANDLE extcap_pipe_h;
218  HANDLE extcap_control_in_h;
219  HANDLE extcap_control_out_h;
220 #endif
221  gchar *extcap_control_in;
222  gchar *extcap_control_out;
223 #ifdef CAN_SET_CAPTURE_BUFFER_SIZE
224  int buffer_size;
225 #endif
226  gboolean monitor_mode;
227 #ifdef HAVE_PCAP_REMOTE
228  capture_source src_type;
229  gchar *remote_host;
230  gchar *remote_port;
231  capture_auth auth_type;
232  gchar *auth_username;
233  gchar *auth_password;
234  gboolean datatx_udp;
235  gboolean nocap_rpcap;
236  gboolean nocap_local;
237 #endif
238 #ifdef HAVE_PCAP_SETSAMPLING
239  capture_sampling sampling_method;
240  int sampling_param;
241 #endif
242  gchar *timestamp_type; /* requested timestamp as string */
243  int timestamp_type_id; /* Timestamp type to pass to pcap_set_tstamp_type.
244  only valid if timestamp_type != NULL */
246 
248 typedef struct capture_options_tag {
249  /* general */
250  GList *(*get_iface_list)(int *, gchar **);
252  GArray *ifaces;
255  GArray *all_ifaces;
260  guint num_selected;
261 
262  /*
263  * Options to be applied to all interfaces.
264  *
265  * Some of these can be set from the GUI, others can't; setting
266  * the link-layer header type, for example, doesn't necessarily
267  * make sense, as different interfaces may support different sets
268  * of link-layer header types.
269  *
270  * Some that can't be set from the GUI can be set from the command
271  * line, by specifying them before any interface is specified.
272  * This includes the link-layer header type, so if somebody asks
273  * for a link-layer header type that an interface on which they're
274  * capturing doesn't support, we should report an error and fail
275  * to capture.
276  *
277  * These can be overridden per-interface.
278  */
279  interface_options default_options;
280 
281  gboolean saving_to_file;
282  gchar *save_file;
283  gboolean group_read_access;
284  gboolean use_pcapng;
287  /* GUI related */
288  gboolean real_time_mode;
289  gboolean show_info;
290  gboolean restart;
291  gchar *orig_save_file;
293  /* multiple files (and ringbuffer) */
294  gboolean multi_files_on;
296  gboolean has_file_duration;
297  gdouble file_duration;
298  gboolean has_file_interval;
299  gint32 file_interval;
300  gboolean has_file_packets;
304  guint32 ring_num_files;
305  gboolean has_nametimenum;
307  /* autostop conditions */
325  gboolean print_file_names;
327  gchar *print_name_to;
328  gchar *temp_dir;
330  /* internally used (don't touch from outside) */
331  gboolean output_to_pipe;
332  gboolean capture_child;
335  gchar *compress_type;
336  gchar *closed_msg;
340 
341 /*
342  * Initialize the capture_options with some reasonable values, and
343  * provide a routine it can use to fetch a list of capture options
344  * if it needs it.
345  *
346  * (Getting that list might involve running dumpcap, so we don't want
347  * to waste time doing that if we don't have to.)
348  */
349 extern void
350 capture_opts_init(capture_options *capture_opts, GList *(*get_iface_list)(int *, gchar **));
351 
352 /* clean internal structures */
353 extern void
354 capture_opts_cleanup(capture_options *capture_opts);
355 
356 /* set a command line option value */
357 extern int
358 capture_opts_add_opt(capture_options *capture_opts, int opt, const char *ws_optarg);
359 
360 /* log content of capture_opts */
361 extern void
362 capture_opts_log(const char *domain, enum ws_log_level level, capture_options *capture_opts);
363 
364 /* List supported file types for capturing. This is intentionally smaller
365  * than the list supported by libwiretap (and dumpcap isn't linked with
366  * libwiretap.) */
367 extern void
368 capture_opts_list_file_types(void);
369 
370 enum caps_query {
371  CAPS_QUERY_LINK_TYPES = 0x1,
372  CAPS_QUERY_TIMESTAMP_TYPES = 0x2
373 };
374 
375 /* print interface capabilities, including link layer types */
376 extern int
377 capture_opts_print_if_capabilities(if_capabilities_t *caps,
378  const interface_options *interface_opts,
379  int queries);
380 
381 /* print list of interfaces */
382 extern void
383 capture_opts_print_interfaces(GList *if_list);
384 
385 /* trim the snaplen entry */
386 extern void
387 capture_opts_trim_snaplen(capture_options *capture_opts, int snaplen_min);
388 
389 /* trim the ring_num_files entry */
390 extern void
391 capture_opts_trim_ring_num_files(capture_options *capture_opts);
392 
393 /* pick default interface if none was specified */
394 extern int
395 capture_opts_default_iface_if_necessary(capture_options *capture_opts,
396  const char *capture_device);
397 
398 extern void
399 capture_opts_del_iface(capture_options *capture_opts, guint if_index);
400 
401 extern void
402 interface_opts_free(interface_options *interface_opts);
403 
404 extern interface_options*
405 interface_opts_from_if_info(capture_options *capture_opts, const if_info_t *if_info);
406 
407 extern void
408 collect_ifaces(capture_options *capture_opts);
409 
410 extern void
411 capture_opts_free_link_row(gpointer elem);
412 
413 extern void
414 capture_opts_free_interface_t(interface_t *device);
415 
416 /* Default capture buffer size in Mbytes. */
417 #define DEFAULT_CAPTURE_BUFFER_SIZE 2
418 
419 /* Default update interval in milliseconds */
420 #define DEFAULT_UPDATE_INTERVAL 100
421 
422 #ifdef __cplusplus
423 }
424 #endif /* __cplusplus */
425 
426 #endif /* __CAPTURE_OPTS_H__ */
427 
428 /*
429  * Editor modelines - https://www.wireshark.org/tools/modelines.html
430  *
431  * Local variables:
432  * c-basic-offset: 4
433  * tab-width: 8
434  * indent-tabs-mode: nil
435  * End:
436  *
437  * vi: set shiftwidth=4 tabstop=8 expandtab:
438  * :indentSize=4:tabSize=8:noTabs=true:
439  */
struct capture_options_tag capture_options
Definition: mcast_stream.h:30
Definition: capture_opts.h:248
gchar * temp_dir
Definition: capture_opts.h:328
gboolean stop_after_extcaps
Definition: capture_opts.h:333
gchar * closed_msg
Definition: capture_opts.h:336
gboolean has_ring_num_files
Definition: capture_opts.h:303
int ifaces_err
Definition: capture_opts.h:257
gboolean has_nametimenum
Definition: capture_opts.h:305
gint32 file_interval
Definition: capture_opts.h:299
gboolean capture_child
Definition: capture_opts.h:332
guint extcap_terminate_id
Definition: capture_opts.h:337
gchar * save_file
Definition: capture_opts.h:282
gboolean has_autostop_duration
Definition: capture_opts.h:321
GArray * ifaces
Definition: capture_opts.h:252
gboolean has_file_packets
Definition: capture_opts.h:300
gboolean wait_for_extcap_cbs
Definition: capture_opts.h:334
gboolean multi_files_on
Definition: capture_opts.h:294
GArray * all_ifaces
Definition: capture_opts.h:255
gboolean use_pcapng
Definition: capture_opts.h:284
gboolean print_file_names
Definition: capture_opts.h:325
gboolean real_time_mode
Definition: capture_opts.h:288
gdouble file_duration
Definition: capture_opts.h:297
int autostop_packets
Definition: capture_opts.h:314
int autostop_files
Definition: capture_opts.h:310
gchar * orig_save_file
Definition: capture_opts.h:291
guint32 ring_num_files
Definition: capture_opts.h:304
gboolean has_file_interval
Definition: capture_opts.h:298
gboolean group_read_access
Definition: capture_opts.h:283
gchar * print_name_to
Definition: capture_opts.h:327
guint32 autostop_filesize
Definition: capture_opts.h:320
gboolean has_autostop_packets
Definition: capture_opts.h:312
gdouble autostop_duration
Definition: capture_opts.h:323
gchar * ifaces_err_info
Definition: capture_opts.h:259
filter_list_t * capture_filters_list
Definition: capture_opts.h:338
gboolean output_to_pipe
Definition: capture_opts.h:331
int file_packets
Definition: capture_opts.h:302
guint update_interval
Definition: capture_opts.h:285
gboolean has_autostop_filesize
Definition: capture_opts.h:318
gboolean restart
Definition: capture_opts.h:290
gboolean show_info
Definition: capture_opts.h:289
gboolean has_autostop_files
Definition: capture_opts.h:308
gboolean has_autostop_written_packets
Definition: capture_opts.h:315
int autostop_written_packets
Definition: capture_opts.h:317
gchar * compress_type
Definition: capture_opts.h:335
gboolean has_file_duration
Definition: capture_opts.h:296
gboolean saving_to_file
Definition: capture_opts.h:281
Definition: filter_files.h:53
Definition: capture_ifinfo.h:43
Definition: capture_ifinfo.h:57
Definition: iptrace.c:58
Definition: capture_opts.h:196
Definition: androiddump.c:219
Definition: capture_opts.h:159