1 .\" Copyright (c) 1988-1990 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that: (1) source code distributions
6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
7 .\" distributions including binary code include the above copyright notice and
8 .\" this paragraph in its entirety in the documentation or other materials
9 .\" provided with the distribution, and (3) all advertising materials mentioning
10 .\" features or use of this software display the following acknowledgement:
11 .\" ``This product includes software developed by the University of California,
12 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
13 .\" the University nor the names of its contributors may be used to endorse
14 .\" or promote products derived from this software without specific prior
15 .\" written permission.
16 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
17 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
20 .\" $FreeBSD: src/usr.sbin/tcpdump/tcpslice/tcpslice.1,v 1.7.2.8 2003/03/11 22:31:33 trhodes Exp $
21 .\" $DragonFly: src/usr.sbin/tcpdump/tcpslice/tcpslice.1,v 1.2 2003/06/17 04:30:03 dillon Exp $
28 .Nd extract pieces of and/or glue together tcpdump files
33 .Op Ar start-time Op end-time
38 utility extracts portions of packet-trace files generated using
42 It can also be used to glue together several such files, as discussed
45 The basic operation of
49 all packets from its input file(s) whose timestamps fall
50 within a given range. The starting and ending times of the range
51 may be specified on the command line. All ranges are inclusive.
52 The starting time defaults
53 to the time of the first packet in the first input file; we call
56 The ending time defaults to ten years after the starting time.
64 (assuming the file does not include more than
65 ten years' worth of data).
67 There are a number of ways to specify times. The first is using
68 Unix timestamps of the form
70 (this is the format specified by
76 specifies 38 seconds and 765,400 microseconds
77 after 8:51PM PDT, Sept. 25, 1990.
79 All examples in this manual are given
80 for PDT times, but when displaying times and interpreting times symbolically
83 uses the local timezone, regardless of the timezone in which the
85 file was generated. The daylight-savings setting used is that which is
86 appropriate for the local timezone at the date in question. For example,
87 times associated with summer months will usually include daylight-savings
88 effects, and those with winter months will not.
90 Times may also be specified relative
93 (when specifying a starting time)
94 or the starting time (when specifying an ending time)
95 by preceding a numeric value in seconds with a `+'.
96 For example, a starting time of
98 indicates 200 seconds after the
100 and the two arguments
102 indicate from 200 seconds after the
104 through 500 seconds after the
107 Times may also be specified in terms of years (y), months (m), days (d),
108 hours (h), minutes (m), seconds (s), and microseconds(u). For example,
109 the Unix timestamp 654321098.7654 discussed above could also be expressed
111 .Em 90y9m25d20h51m38s765400u .
113 When specifying times using this style, fields that are omitted default
114 as follows. If the omitted field is a unit
116 than that of the first specified field, then its value defaults to
117 the corresponding value taken from either
119 (if the starting time is being specified) or the starting time
120 (if the ending time is being specified).
121 If the omitted field is a unit
123 than that of the first specified field, then it defaults to zero.
124 For example, suppose that the input file has a
126 of the Unix timestamp mentioned above, i.e., 38 seconds and 765,400 microseconds
127 after 8:51PM PDT, Sept. 25, 1990. To specify 9:36PM PDT (exactly) on the
128 same date we could use
130 To specify a range from 9:36PM PDT through 1:54AM PDT the next day we
132 .Em 21h36m 26d1h54m .
134 Relative times can also be specified when using the
136 format. Omitted fields then default to 0 if the unit of the field is
138 than that of the first specified field, and to the corresponding value
139 taken from either the
141 or the starting time if the omitted field's unit is
143 than that of the first specified field. Given a
145 of the Unix timestamp mentioned above,
147 specifies a range from 10:00PM PDT on that date through 11:10PM PDT, and
149 specifies a range from 38.7654 seconds after 9:51PM PDT through 38.7654
150 seconds after 11:01PM PDT. The first hour of the file could be extracted
156 format there is an ambiguity between using
158 for `month' or for `minute'. The ambiguity is resolved as follows: if an
160 field is followed by a
162 field then it is interpreted as specifying months; otherwise it
165 If more than one input file is specified then
167 first copies packets lying in the given range from the first file; it
168 then increases the starting time of the range to lie just beyond the
169 timestamp of the last packet in the first file, repeats the process
170 with the second file, and so on. Thus files with interleaved packets
173 merged. For a given file, only packets that are newer than any in the
174 preceding files will be considered. This mechanism avoids any possibility
175 of a packet occurring more than once in the output.
184 reports the timestamps of the first and last packets in each input file
185 and exits. Only one of these three options may be specified.
187 The following options are available:
188 .Bl -tag -width indent
190 Dump the start and end times specified by the given range and
191 exit. This option is useful for checking that the given range actually
192 specifies the times you think it does. If one of
197 has been specified then the times are dumped in the corresponding
198 format; otherwise, raw format
202 Dump the timestamps of the first and last packets in each input file
203 as raw timestamps (i.e., in the form
204 .Em sssssssss.uuuuuu ) .
208 except the timestamps are dumped in human-readable format, similar
214 except the timestamps are dumped in
218 format discussed above.
228 .An Vern Paxson Aq vern@ee.lbl.gov ,
229 of Lawrence Berkeley Laboratory, University of California, Berkeley, CA.
231 An input filename that beings with a digit or a `+' can be confused
232 with a start/end time. Such filenames can be specified with a
233 leading `./'; for example, specify the file `04Jul76.trace' as
238 utility cannot read its input from
240 since it uses random-access
241 to rummage through its input files.
245 utility refuses to write to its output if it is a terminal
248 This is not a bug but a feature,
249 to prevent it from spraying binary data to the user's terminal.
250 Note that this means you must either redirect
258 utility will not work properly on
260 files spanning more than one year;
261 with files containing portions of packets whose original length was
262 more than 65,535 bytes; nor with files containing fewer than three packets.
264 the error message: `couldn't find final packet in file'. These problems
265 are due to the interpolation scheme used by
267 to greatly speed up its processing when dealing with large trace files.
270 can efficiently extract slices from the middle of trace files of any
271 size, and can also work with truncated trace files (i.e., the final packet
272 in the file is only partially present, typically due to
274 being ungracefully killed).