diff options
Diffstat (limited to 'usr.sbin/tcpdump/tcpslice/tcpslice.1')
-rw-r--r-- | usr.sbin/tcpdump/tcpslice/tcpslice.1 | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/usr.sbin/tcpdump/tcpslice/tcpslice.1 b/usr.sbin/tcpdump/tcpslice/tcpslice.1 new file mode 100644 index 000000000000..b130f2c22a7e --- /dev/null +++ b/usr.sbin/tcpdump/tcpslice/tcpslice.1 @@ -0,0 +1,260 @@ +.\" @(#) $Header: tcpslice.1,v 1.2 91/10/16 11:42:46 vern Exp $ (LBL) +.\" +.\" Copyright (c) 1988-1990 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that: (1) source code distributions +.\" retain the above copyright notice and this paragraph in its entirety, (2) +.\" distributions including binary code include the above copyright notice and +.\" this paragraph in its entirety in the documentation or other materials +.\" provided with the distribution, and (3) all advertising materials mentioning +.\" features or use of this software display the following acknowledgement: +.\" ``This product includes software developed by the University of California, +.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of +.\" the University nor the names of its contributors may be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.TH TCPSLICE 1 "14 Oct 1991" +.SH NAME +tcpslice \- extract pieces of and/or glue together tcpdump files +.SH SYNOPSIS +.na +.B tcpslice +[ +.B \-dRrt +] [ +.B \-w +.I file +] +.br +.ti +9 +[ +.I start-time +[ +.I end-time +] ] +.I file ... +.br +.ad +.SH DESCRIPTION +.LP +.I Tcpslice +is a program for extracting portions of packet-trace files generated using +\fItcpdump(l)\fP's +.B \-w +flag. +It can also be used to glue together several such files, as discussed +below. +.LP +The basic operation of +.I tcpslice +is to copy to +.I 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 +.I first time. +The ending time defaults to ten years after the starting time. +Thus, the command +.I tcpslice trace-file +simply copies +.I trace-file +to \fIstdout\fP (assuming the file does not include more than +ten years' worth of data). +.LP +There are a number of ways to specify times. The first is using +Unix timestamps of the form +.I sssssssss.uuuuuu +(this is the format specified by \fItcpdump\fP's +.B \-tt +flag). +For example, +.B 654321098.7654 +specifies 38 seconds and 765,400 microseconds +after 8:51PM PDT, Sept. 25, 1990. +.LP +All examples in this manual are given +for PDT times, but when displaying times and interpreting times symbolically +as discussed below, +.I tcpslice +uses the local timezone, regardless of the timezone in which the \fItcpdump\fP +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. +.LP +Times may also be specified relative +to either the +.I 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 +.B +200 +indicates 200 seconds after the +.I first time, +and the two arguments +.B +200 +300 +indicate from 200 seconds after the +.I first time +through 500 seconds after the +.I first time. +.LP +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 +.B 90y9m25d20h51m38s765400u. +.LP +When specifying times using this style, fields that are omitted default +as follows. If the omitted field is a unit +.I greater +than that of the first specified field, then its value defaults to +the corresponding value taken from either +.I 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 +.I less +than that of the first specified field, then it defaults to zero. +For example, suppose that the input file has a +.I 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 +.B 21h36m. +To specify a range from 9:36PM PDT through 1:54AM PDT the next day we +could use +.B 21h36m 26d1h54m. +.LP +Relative times can also be specified when using the +.I ymdhmsu +format. Omitted fields then default to 0 if the unit of the field is +.I greater +than that of the first specified field, and to the corresponding value +taken from either the +.I first time +or the starting time if the omitted field's unit is +.I less +than that of the first specified field. Given a +.I first time +of the Unix timestamp mentioned above, +.B 22h +1h10m +specifies a range from 10:00PM PDT on that date through 11:10PM PDT, and +.B +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 +.B +0 +1h. +.LP +Note that with the +.I ymdhmsu +format there is an ambiguity between using +.I m +for `month' or for `minute'. The ambiguity is resolved as follows: if an +.I m +field is followed by a +.I d +field then it is interpreted as specifying months; otherwise it +specifies minutes. +.LP +If more than one input file is specified then +.I 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 +.I 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. +.SH OPTIONS +.LP +If any of +.B \-R, +.B \-r +or +.B \-t +are specified then +.I 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. +.TP +.B \-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 +.B \-R, +.B \-r +or +.B \-t +has been specified then the times are dumped in the corresponding +format; otherwise, raw format (\fB \-R\fP) is used. +.TP +.B \-R +Dump the timestamps of the first and last packets in each input file +as raw timestamps (i.e., in the form \fI sssssssss.uuuuuu\fP). +.TP +.B \-r +Same as +.B \-R +except the timestamps are dumped in human-readable format, similar +to that used by \fI date(1)\fP. +.TP +.B \-t +Same as +.B \-R +except the timestamps are dumped in +.I tcpslice +format, i.e., in the +.I ymdhmsu +format discussed above. +.TP +.B \-w +Direct the output to \fIfile\fR rather than \fIstdout\fP. +.SH "SEE ALSO" +tcpdump(l) +.SH AUTHOR +Vern Paxson (vern@ee.lbl.gov), of +Lawrence Berkeley Laboratory, University of California, Berkeley, CA. +.SH BUGS +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'. +.LP +.I tcpslice +cannot read its input from \fIstdin\fP, since it uses random-access +to rummage through its input files. +.LP +.I tcpslice +refuses to write to its output if it is a terminal +(as indicated by \fIisatty(3)\fP). 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 \fIstdout\fP or specify an +output file via \fB\-w\fP. +.LP +.I tcpslice +will not work properly on \fItcpdump\fP 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 +.I tcpslice +to greatly speed up its processing when dealing with large trace files. +Note that +.I 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 \fItcpdump\fP +being ungracefully killed). |