usr.sbin/tcpdump/tcpslice/tcpslice.1

   1 .\" Copyright (c) 1988-1990 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   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.
  19 .\"
  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 $
  22 .\"
  23 .Dd October 14, 1991
  24 .Dt TCPSLICE 1
  25 .Os
  26 .Sh NAME
  27 .Nm tcpslice
  28 .Nd extract pieces of and/or glue together tcpdump files
  29 .Sh SYNOPSIS
  30 .Nm
  31 .Op Fl dRrt
  32 .Op Fl w Ar file
  33 .Op Ar start-time Op end-time
  34 .Ar
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 utility extracts portions of packet-trace files generated using
  39 .Xr tcpdump 1 Ns 's
  40 .Fl w
  41 flag.
  42 It can also be used to glue together several such files, as discussed
  43 below.
  44 .Pp
  45 The basic operation of
  46 .Nm
  47 is to copy to
  48 .Pa stdout
  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
  54 this the
  55 .Em first time .
  56 The ending time defaults to ten years after the starting time.
  57 Thus, the command
  58 .Nm
  59 .Ar trace-file
  60 simply copies
  61 .Ar trace-file
  62 to
  63 .Pa stdout
  64 (assuming the file does not include more than
  65 ten years' worth of data).
  66 .Pp
  67 There are a number of ways to specify times.  The first is using
  68 Unix timestamps of the form
  69 .Em sssssssss.uuuuuu
  70 (this is the format specified by
  71 .Xr tcpdump 1 Ns 's
  72 .Fl tt
  73 flag).
  74 For example,
  75 .Em 654321098.7654
  76 specifies 38 seconds and 765,400 microseconds
  77 after 8:51PM PDT, Sept. 25, 1990.
  78 .Pp
  79 All examples in this manual are given
  80 for PDT times, but when displaying times and interpreting times symbolically
  81 as discussed below,
  82 .Nm
  83 uses the local timezone, regardless of the timezone in which the
  84 .Xr tcpdump 1
  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.
  89 .Pp
  90 Times may also be specified relative
  91 to either the
  92 .Em first time
  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
  97 .Em +200
  98 indicates 200 seconds after the
  99 .Em first time ,
 100 and the two arguments
 101 .Em +200 +300
 102 indicate from 200 seconds after the
 103 .Em first time
 104 through 500 seconds after the
 105 .Em first time .
 106 .Pp
 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
 110 as
 111 .Em 90y9m25d20h51m38s765400u .
 112 .Pp
 113 When specifying times using this style, fields that are omitted default
 114 as follows.  If the omitted field is a unit
 115 .Em greater
 116 than that of the first specified field, then its value defaults to
 117 the corresponding value taken from either
 118 .Em first time
 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
 122 .Em less
 123 than that of the first specified field, then it defaults to zero.
 124 For example, suppose that the input file has a
 125 .Em first time
 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
 129 .Em 21h36m .
 130 To specify a range from 9:36PM PDT through 1:54AM PDT the next day we
 131 could use
 132 .Em 21h36m 26d1h54m .
 133 .Pp
 134 Relative times can also be specified when using the
 135 .Em ymdhmsu
 136 format.  Omitted fields then default to 0 if the unit of the field is
 137 .Em greater
 138 than that of the first specified field, and to the corresponding value
 139 taken from either the
 140 .Em first time
 141 or the starting time if the omitted field's unit is
 142 .Em less
 143 than that of the first specified field.  Given a
 144 .Em first time
 145 of the Unix timestamp mentioned above,
 146 .Em 22h +1h10m
 147 specifies a range from 10:00PM PDT on that date through 11:10PM PDT, and
 148 .Em +1h +1h10m
 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
 151 using
 152 .Em +0 +1h .
 153 .Pp
 154 Note that with the
 155 .Em ymdhmsu
 156 format there is an ambiguity between using
 157 .Em m
 158 for `month' or for `minute'.  The ambiguity is resolved as follows: if an
 159 .Em m
 160 field is followed by a
 161 .Em d
 162 field then it is interpreted as specifying months; otherwise it
 163 specifies minutes.
 164 .Pp
 165 If more than one input file is specified then
 166 .Nm
 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
 171 are
 172 .Em not
 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.
 176 .Sh OPTIONS
 177 If any of
 178 .Fl R ,
 179 .Fl r
 180 or
 181 .Fl t
 182 are specified then
 183 .Nm
 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.
 186 .Pp
 187 The following options are available:
 188 .Bl -tag -width indent
 189 .It Fl d
 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
 193 .Fl R ,
 194 .Fl r
 195 or
 196 .Fl t
 197 has been specified then the times are dumped in the corresponding
 198 format; otherwise, raw format
 199 .Pq Fl R
 200 is used.
 201 .It Fl R
 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 ) .
 205 .It Fl r
 206 Same as
 207 .Fl R
 208 except the timestamps are dumped in human-readable format, similar
 209 to that used by
 210 .Xr date 1 .
 211 .It Fl t
 212 Same as
 213 .Fl R
 214 except the timestamps are dumped in
 215 .Nm
 216 format, i.e., in the
 217 .Em ymdhmsu
 218 format discussed above.
 219 .It Fl w Ar file
 220 Direct the output to
 221 .Ar file
 222 rather than
 223 .Pa stdout .
 224 .El
 225 .Sh SEE ALSO
 226 .Xr tcpdump 1
 227 .Sh AUTHORS
 228 .An Vern Paxson Aq vern@ee.lbl.gov ,
 229 of Lawrence Berkeley Laboratory, University of California, Berkeley, CA.
 230 .Sh BUGS
 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
 234 `./04Jul76.trace'.
 235 .Pp
 236 The
 237 .Nm
 238 utility cannot read its input from
 239 .Pa stdin ,
 240 since it uses random-access
 241 to rummage through its input files.
 242 .Pp
 243 The
 244 .Nm
 245 utility refuses to write to its output if it is a terminal
 246 (as indicated by
 247 .Xr isatty 3 ) .
 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
 251 .Pa stdout
 252 or specify an
 253 output file via
 254 .Fl w .
 255 .Pp
 256 The
 257 .Nm
 258 utility will not work properly on
 259 .Xr tcpdump 1
 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.
 263 Such files result in
 264 the error message: `couldn't find final packet in file'.  These problems
 265 are due to the interpolation scheme used by
 266 .Nm
 267 to greatly speed up its processing when dealing with large trace files.
 268 Note that
 269 .Nm
 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
 273 .Xr tcpdump 1
 274 being ungracefully killed).