instead of repeating the capture file format description over and over again (this...
[obnox/wireshark/wip.git] / doc / editcap.pod
1
2 =head1 NAME
3
4 editcap - Edit and/or translate the format of capture files
5
6 =head1 SYNOPSYS
7
8 B<editcap>
9 S<[ B<-c> E<lt>packets per fileE<gt> ]>
10 S<[ B<-C> E<lt>choplenE<gt> ]>
11 S<[ B<-E> E<lt>error probabilityE<gt> ]>
12 S<[ B<-F> E<lt>file formatE<gt> ]>
13 S<[ B<-h> ]>
14 S<[ B<-r> ]>
15 S<[ B<-s> E<lt>snaplenE<gt> ]>
16 S<[ B<-t> E<lt>time adjustmentE<gt> ]>
17 S<[ B<-T> E<lt>encapsulation typeE<gt> ]>
18 S<[ B<-v> ]>
19 I<infile>
20 I<outfile>
21 S<[ I<packet#>[-I<packet#>] ... ]>
22
23 =head1 DESCRIPTION
24
25 B<Editcap> is a program that reads some or all of the captured packets from the 
26 I<infile>, optionally converts them in various ways and writes the 
27 resulting packets to the capture I<outfile> (or outfiles). 
28
29 By default, it reads all packets from the I<infile> and writes them to the 
30 I<outfile> in libpcap file format.
31
32 A list of packet numbers can be specified on the command line; ranges of 
33 packet numbers can be specified as I<start>-I<end>, referring to all packets 
34 from I<start> to I<end>.
35 The selected packets with those numbers will I<not> be written to the 
36 capture file. 
37 If the B<-r> flag is specified, the whole packet selection is reversed; 
38 in that case I<only> the selected packets will be written to the capture file.
39
40 B<Editcap> is able to detect, read and write the same capture files that 
41 are supported by B<Ethereal>.
42 The input file doesn't need a specific filename extension, the file 
43 format and an optional gzip compression will be automatically detected.
44 The I<capture file format> section of I<ethereal(1)> or
45 I<http://www.ethereal.com/docs/man-pages/ethereal.1.html>
46 provides a detailed description.
47
48 B<Editcap> can write the file in several output formats. The B<-F>
49 flag can be used to specify the format in which to write the capture
50 file, B<editcap -F> provides a list of the available output formats.
51
52 =head1 OPTIONS
53
54 =over 4
55
56 =item -c  E<lt>packets per fileE<gt>
57
58 Sets the maximum number of packets per output file. Each output file will 
59 be created with a suffix -nnnnn, starting with 00000. If the specified 
60 number of packets are written to the output file, the next output file is 
61 opened. The default is to use a single output file.
62
63 =item -C  E<lt>choplenE<gt>
64
65 Sets the chop length to use when writing the packet data.
66 Each packet is chopped at the packet end by a few <choplen> bytes of data.
67
68 This is useful in the rare case that the conversion between two file 
69 formats leaves some random bytes at the end of each packet.
70
71 =item -E  E<lt>error probabilityE<gt>
72
73 Sets the probabilty that bytes in the output file are randomly changed.
74 B<Editcap> uses that probability (between 0.0 and 1.0 inclusive) 
75 to apply errors to each data byte in the file.  For instance, a 
76 probability of 0.02 means that each byte has a 2% chance of having an error.
77
78 This option is meant to be used for fuzz-testing protocol dissectors.
79
80 =item -F  E<lt>file formatE<gt>
81
82 Sets the file format of the output capture file.
83 B<Editcap> can write the file in several formats, B<editcap -F> 
84 provides a list of the available output formats. The default
85 is the B<libpcap> format.
86
87 =item -h
88
89 Prints the version and options and exits.
90
91 =item -r
92
93 Reverse the packet selection.
94 Causes the packets whose packet numbers are specified on the command
95 line to be written to the output capture file, instead of discarding them.
96
97 =item -s  E<lt>snaplenE<gt>
98
99 Sets the snapshot length to use when writing the data.
100 If the B<-s> flag is used to specify a snapshot length, packets in the
101 input file with more captured data than the specified snapshot length
102 will have only the amount of data specified by the snapshot length
103 written to the output file.  
104
105 This may be useful if the program that is
106 to read the output file cannot handle packets larger than a certain size
107 (for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
108 appear to reject Ethernet packets larger than the standard Ethernet MTU,
109 making them incapable of handling gigabit Ethernet captures if jumbo
110 packets were used).
111
112 =item -t  E<lt>time adjustmentE<gt>
113
114 Sets the time adjustment to use on selected packets.
115 If the B<-t> flag is used to specify a time adjustment, the specified
116 adjustment will be applied to all selected packets in the capture file.
117 The adjustment is specified as [-]I<seconds>[I<.fractional seconds>].
118 For example, B<-t> 3600 advances the timestamp on selected packets by one
119 hour while B<-t> -0.5 reduces the timestamp on selected packets by
120 one-half second.  
121
122 This feature is useful when synchronizing dumps
123 collected on different machines where the time difference between the
124 two machines is known or can be estimated.
125
126 =item -T  E<lt>encapsulation typeE<gt>
127
128 Sets the packet encapsulation type of the output capture file.
129 If the B<-T> flag is used to specify an encapsulation type, the
130 encapsulation type of the output capture file will be forced to the
131 specified type. 
132 B<editcap -T> provides a list of the available types. The default
133 type is the one appropriate to the encapsulation type of the input 
134 capture file.
135
136 Note: this merely
137 forces the encapsulation type of the output file to be the specified
138 type; the packet headers of the packets will not be translated from the
139 encapsulation type of the input capture file to the specified
140 encapsulation type (for example, it will not translate an Ethernet
141 capture to an FDDI capture if an Ethernet capture is read and 'B<-T
142 fddi>' is specified).
143
144 =item -v
145
146 Causes B<editcap> to print verbose messages while it's working.
147
148 =back
149
150 =head1 EXAMPLES
151
152 To see more detailed description of the options use:
153
154     editcap -h
155
156 To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use:
157
158     editcap -s 64 -F snoop capture.pcap shortcapture.snoop
159
160 To delete packet 1000 from the capture file use:
161
162     editcap capture.pcap sans1000.pcap 1000
163
164 To limit a capture file to packets from number 200 to 750 (inclusive) use:
165
166     editcap -r capture.pcap small.pcap 200-750
167
168 To get all packets from number 1-500 (inclusive) use:
169
170     editcap -r capture.pcap 500.pcap 1-500
171
172 or
173
174     editcap capture.pcap 500.pcap 501-9999999
175
176 To filter out packets 10 to 20 and 30 to 40 into a new file use:
177
178     editcap capture.pcap selection.pcap 10-20 30-40
179
180 To introduce 5% random errors in a capture file use:
181
182 =over 4
183
184   editcap -E 0.05 capture.pcap capture_error.pcap
185
186 =back
187
188 =head1 SEE ALSO
189
190 I<tcpdump(8)>, I<pcap(3)>, I<ethereal(1)>, I<mergecap(1)>
191
192 =head1 NOTES
193
194 B<Editcap> is part of the B<Ethereal> distribution.  The latest version
195 of B<Ethereal> can be found at B<http://www.ethereal.com>.
196
197 HTML versions of the Ethereal project man pages are available at:
198 http://www.ethereal.com/docs/man-pages
199
200 =head1 AUTHORS
201
202   Original Author
203   -------- ------
204   Richard Sharpe           <sharpe[AT]ns.aus.com>
205
206
207   Contributors
208   ------------
209   Guy Harris               <guy[AT]alum.mit.edu>
210   Ulf Lamping              <ulf.lamping[AT]web.de>