Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
TCPSLICE(1)		  BSD General Commands Manual		   TCPSLICE(1)

     tcpslice -- extract pieces	of and/or glue together	tcpdump	files

     tcpslice [-dRrt] [-w file]	[start-time [end-time]]	file ...

     The tcpslice utility extracts portions of packet-trace files generated
     using tcpdump(1)'s	-w flag.  It can also be used to glue together several
     such files, as discussed below.

     The basic operation of tcpslice is	to copy	to stdout all packets from its
     input file(s) whose timestamps fall within	a given	range.	The starting
     and ending	times of the range may be specified on the command line.  All
     ranges are	inclusive.  The	starting time defaults to the time of the
     first packet in the first input file; we call this	the first time.	 The
     ending time defaults to ten years after the starting time.	 Thus, the
     command tcpslice trace-file simply	copies trace-file to stdout (assuming
     the file does not include more than ten years' worth of data).

     There are a number	of ways	to specify times.  The first is	using Unix
     timestamps	of the form sssssssss.uuuuuu (this is the format specified by
     tcpdump(1)'s -tt flag).  For example, 654321098.7654 specifies 38 seconds
     and 765,400 microseconds after 8:51PM PDT,	Sept. 25, 1990.

     All examples in this manual are given for PDT times, but when displaying
     times and interpreting times symbolically as discussed below, tcpslice
     uses the local timezone, regardless of the	timezone in which the
     tcpdump(1)	file was generated.  The daylight-savings setting used is that
     which is appropriate for the local	timezone at the	date in	question.  For
     example, times associated with summer months will usually include day-
     light-savings effects, and	those with winter months will not.

     Times may also be specified relative to either the	first time (when spec-
     ifying a starting time) or	the starting time (when	specifying an ending
     time) by preceding	a numeric value	in seconds with	a `+'.	For example, a
     starting time of +200 indicates 200 seconds after the first time, and the
     two arguments +200	+300 indicate from 200 seconds after the first time
     through 500 seconds after the first time.

     Times may also be specified in terms of years (y),	months (m), days (d),
     hours (h),	minutes	(m), seconds (s), and microseconds(u).	For example,
     the Unix timestamp	654321098.7654 discussed above could also be expressed
     as	90y9m25d20h51m38s765400u.

     When specifying times using this style, fields that are omitted default
     as	follows.  If the omitted field is a unit greater than that of the
     first specified field, then its value defaults to the corresponding value
     taken from	either first time (if the starting time	is being specified) or
     the starting time (if the ending time is being specified).	 If the	omit-
     ted field is a unit less than that	of the first specified field, then it
     defaults to zero.	For example, suppose that the input file has a first
     time of the Unix timestamp	mentioned above, i.e., 38 seconds and 765,400
     microseconds after	8:51PM PDT, Sept. 25, 1990.  To	specify	9:36PM PDT
     (exactly) on the same date	we could use 21h36m.  To specify a range from
     9:36PM PDT	through	1:54AM PDT the next day	we could use 21h36m 26d1h54m.

     Relative times can	also be	specified when using the ymdhmsu format.
     Omitted fields then default to 0 if the unit of the field is greater than
     that of the first specified field,	and to the corresponding value taken
     from either the first time	or the starting	time if	the omitted field's
     unit is less than that of the first specified field.  Given a first time
     of	the Unix timestamp mentioned above, 22h	+1h10m specifies a range from
     10:00PM PDT on that date through 11:10PM PDT, and +1h +1h10m specifies a
     range from	38.7654	seconds	after 9:51PM PDT through 38.7654 seconds after
     11:01PM PDT.  The first hour of the file could be extracted using +0 +1h.

     Note that with the	ymdhmsu	format there is	an ambiguity between using m
     for `month' or for	`minute'.  The ambiguity is resolved as	follows: if an
     m field is	followed by a d	field then it is interpreted as	specifying
     months; otherwise it specifies minutes.

     If	more than one input file is specified then tcpslice first copies pack-
     ets lying in the given range from the first file; it then increases the
     starting time of the range	to lie just beyond the timestamp of the	last
     packet in the first file, repeats the process with	the second file, and
     so	on.  Thus files	with interleaved packets are not merged.  For a	given
     file, only	packets	that are newer than any	in the preceding files will be
     considered.  This mechanism avoids	any possibility	of a packet occurring
     more than once in the output.

     If	any of -R, -r or -t are	specified then tcpslice	reports	the timestamps
     of	the first and last packets in each input file and exits.  Only one of
     these three options may be	specified.

     The following options are available:

     -d	     Dump the start and	end times specified by the given range and
	     exit.  This option	is useful for checking that the	given range
	     actually specifies	the times you think it does.  If one of	-R, -r
	     or	-t has been specified then the times are dumped	in the corre-
	     sponding format; otherwise, raw format (-R) is used.

     -R	     Dump the timestamps of the	first and last packets in each input
	     file as raw timestamps (i.e., in the form sssssssss.uuuuuu).

     -r	     Same as -R	except the timestamps are dumped in human-readable
	     format, similar to	that used by date(1).

     -t	     Same as -R	except the timestamps are dumped in tcpslice format,
	     i.e., in the ymdhmsu format discussed above.

     -w	file
	     Direct the	output to file rather than stdout.


     Vern Paxson <>, of Lawrence	Berkeley Laboratory, Univer-
     sity of California, Berkeley, CA.

     An	input filename that beings with	a digit	or a `+' can be	confused with
     a start/end time.	Such filenames can be specified	with a leading `./';
     for example, specify the file `04Jul76.trace' as `./04Jul76.trace'.

     The tcpslice utility cannot read its input	from stdin, since it uses ran-
     dom-access	to rummage through its input files.

     The tcpslice utility refuses to write to its output if it is a terminal
     (as indicated by isatty(3)).  This	is not a bug but a feature, to prevent
     it	from spraying binary data to the user's	terminal.  Note	that this
     means you must either redirect stdout or specify an output	file via -w.

     The tcpslice utility will not work	properly on tcpdump(1) files spanning
     more than one year; with files containing portions	of packets whose orig-
     inal length was more than 65,535 bytes; nor with files containing fewer
     than three	packets.  Such files result in the error message: `couldn't
     find final	packet in file'.  These	problems are due to the	interpolation
     scheme used by tcpslice to	greatly	speed up its processing	when dealing
     with large	trace files.  Note that	tcpslice can efficiently extract
     slices from the middle of trace files of any size,	and can	also work with
     truncated trace files (i.e., the final packet in the file is only par-
     tially present, typically due to tcpdump(1) being ungracefully killed).

BSD			       October 14, 1991				   BSD


Want to link to this manual page? Use this URL:

home | help