TCPSLICE(8)						      System Manager's Manual						       TCPSLICE(8)

NAME

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

SYNOPSIS

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

DESCRIPTION

       Tcpslice  is  a	program  for  extracting 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'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, tcp-
       slice uses the local timezone, regardless of the timezone in which the tcpdump 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 daylight-savings effects, and those with winter months will not.

       Times may also be specified relative to either the first time (when specifying 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 omitted field is a unit less than that of the first speci-
       fied 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  speci-
       fies  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 packets 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 pre-
       ceding files will be considered.  This mechanism avoids any possibility of a packet occurring more than once in the output.

OPTIONS

       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.

       -d     Dump  the  start and end times specified by the given range and exit.  This option is useful for checking that the given range actu-
	      ally specifies the times you think it does.  If one of -R, -r or -t has been specified then the times are dumped in the  correspond-
	      ing 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     Direct the output to file rather than stdout.

SEE ALSO

       tcpdump(1)

AUTHORS

       The original author was:

       Vern Paxson, of Lawrence Berkeley Laboratory, University of California, Berkeley, CA.

       It is currently being maintained by tcpdump.org.

       The current version is available in the ``tcpslice'' module of the CVS tree at tcpdump.org; see the tcpdump.org home page at

	      http://www.tcpdump.org/

       for information on anonymous CVS access.

       The original distribution is available via anonymous ftp:

	      ftp://ftp.ee.lbl.gov/tcpslice.tar.Z

BUGS

       Please send problems, bugs, questions, desirable enhancements, etc. to:

	      tcpdump-workers@tcpdump.org

       Please send source code contributions, etc. to:

	      patches@tcpdump.org

       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'.

       tcpslice cannot read its input from stdin, since it uses random-access to rummage through its input files.

       tcpslice 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.

       tcpslice  will  not  work  properly  on tcpdump files spanning more than one year; with files containing portions of packets whose original
       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 partially present, typically due to tcpdump being ungracefully
       killed).

								 21 December 1996						       TCPSLICE(8)