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 .\"
  22 .Dd October 14, 1991
  23 .Dt TCPSLICE 1
  24 .Os
  25 .Sh NAME
  26 .Nm tcpslice
  27 .Nd extract pieces of and/or glue together tcpdump files
  28 .Sh SYNOPSIS
  29 .Nm
  30 .Op Fl dRrt
  31 .Op Fl w Ar file
  32 .Op Ar start-time Op end-time
  33 .Ar
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 utility extracts portions of packet-trace files generated using
  38 .Xr tcpdump 1 Ns 's
  39 .Fl w
  40 flag.
  41 It can also be used to glue together several such files, as discussed
  42 below.
  43 .Pp
  44 The basic operation of
  45 .Nm
  46 is to copy to
  47 .Pa stdout
  48 all packets from its input file(s) whose timestamps fall
  49 within a given range.  The starting and ending times of the range
  50 may be specified on the command line.  All ranges are inclusive.
  51 The starting time defaults
  52 to the time of the first packet in the first input file; we call
  53 this the
  54 .Em first time .
  55 The ending time defaults to ten years after the starting time.
  56 Thus, the command
  57 .Nm
  58 .Ar trace-file
  59 simply copies
  60 .Ar trace-file
  61 to
  62 .Pa stdout
  63 (assuming the file does not include more than
  64 ten years' worth of data).
  65 .Pp
  66 There are a number of ways to specify times.  The first is using
  67 Unix timestamps of the form
  68 .Em sssssssss.uuuuuu
  69 (this is the format specified by
  70 .Xr tcpdump 1 Ns 's
  71 .Fl tt
  72 flag).
  73 For example,
  74 .Em 654321098.7654
  75 specifies 38 seconds and 765,400 microseconds
  76 after 8:51PM PDT, Sept. 25, 1990.
  77 .Pp
  78 All examples in this manual are given
  79 for PDT times, but when displaying times and interpreting times symbolically
  80 as discussed below,
  81 .Nm
  82 uses the local timezone, regardless of the timezone in which the
  83 .Xr tcpdump 1
  84 file was generated.  The daylight-savings setting used is that which is
  85 appropriate for the local timezone at the date in question.  For example,
  86 times associated with summer months will usually include daylight-savings
  87 effects, and those with winter months will not.
  88 .Pp
  89 Times may also be specified relative
  90 to either the
  91 .Em first time
  92 (when specifying a starting time)
  93 or the starting time (when specifying an ending time)
  94 by preceding a numeric value in seconds with a `+'.
  95 For example, a starting time of
  96 .Em +200
  97 indicates 200 seconds after the
  98 .Em first time ,
  99 and the two arguments
 100 .Em +200 +300
 101 indicate from 200 seconds after the
 102 .Em first time
 103 through 500 seconds after the
 104 .Em first time .
 105 .Pp
 106 Times may also be specified in terms of years (y), months (m), days (d),
 107 hours (h), minutes (m), seconds (s), and microseconds(u).  For example,
 108 the Unix timestamp 654321098.7654 discussed above could also be expressed
 109 as
 110 .Em 90y9m25d20h51m38s765400u .
 111 .Pp
 112 When specifying times using this style, fields that are omitted default
 113 as follows.  If the omitted field is a unit
 114 .Em greater
 115 than that of the first specified field, then its value defaults to
 116 the corresponding value taken from either
 117 .Em first time
 118 (if the starting time is being specified) or the starting time
 119 (if the ending time is being specified).
 120 If the omitted field is a unit
 121 .Em less
 122 than that of the first specified field, then it defaults to zero.
 123 For example, suppose that the input file has a
 124 .Em first time
 125 of the Unix timestamp mentioned above, i.e., 38 seconds and 765,400 microseconds
 126 after 8:51PM PDT, Sept. 25, 1990.  To specify 9:36PM PDT (exactly) on the
 127 same date we could use
 128 .Em 21h36m .
 129 To specify a range from 9:36PM PDT through 1:54AM PDT the next day we
 130 could use
 131 .Em 21h36m 26d1h54m .
 132 .Pp
 133 Relative times can also be specified when using the
 134 .Em ymdhmsu
 135 format.  Omitted fields then default to 0 if the unit of the field is
 136 .Em greater
 137 than that of the first specified field, and to the corresponding value
 138 taken from either the
 139 .Em first time
 140 or the starting time if the omitted field's unit is
 141 .Em less
 142 than that of the first specified field.  Given a
 143 .Em first time
 144 of the Unix timestamp mentioned above,
 145 .Em 22h +1h10m
 146 specifies a range from 10:00PM PDT on that date through 11:10PM PDT, and
 147 .Em +1h +1h10m
 148 specifies a range from 38.7654 seconds after 9:51PM PDT through 38.7654
 149 seconds after 11:01PM PDT.  The first hour of the file could be extracted
 150 using
 151 .Em +0 +1h .
 152 .Pp
 153 Note that with the
 154 .Em ymdhmsu
 155 format there is an ambiguity between using
 156 .Em m
 157 for `month' or for `minute'.  The ambiguity is resolved as follows: if an
 158 .Em m
 159 field is followed by a
 160 .Em d
 161 field then it is interpreted as specifying months; otherwise it
 162 specifies minutes.
 163 .Pp
 164 If more than one input file is specified then
 165 .Nm
 166 first copies packets lying in the given range from the first file; it
 167 then increases the starting time of the range to lie just beyond the
 168 timestamp of the last packet in the first file, repeats the process
 169 with the second file, and so on.  Thus files with interleaved packets
 170 are
 171 .Em not
 172 merged.  For a given file, only packets that are newer than any in the
 173 preceding files will be considered.  This mechanism avoids any possibility
 174 of a packet occurring more than once in the output.
 175 .Sh OPTIONS
 176 If any of
 177 .Fl R ,
 178 .Fl r
 179 or
 180 .Fl t
 181 are specified then
 182 .Nm
 183 reports the timestamps of the first and last packets in each input file
 184 and exits.  Only one of these three options may be specified.
 185 .Pp
 186 The following options are available:
 187 .Bl -tag -width indent
 188 .It Fl d
 189 Dump the start and end times specified by the given range and
 190 exit.  This option is useful for checking that the given range actually
 191 specifies the times you think it does.  If one of
 192 .Fl R ,
 193 .Fl r
 194 or
 195 .Fl t
 196 has been specified then the times are dumped in the corresponding
 197 format; otherwise, raw format
 198 .Pq Fl R
 199 is used.
 200 .It Fl R
 201 Dump the timestamps of the first and last packets in each input file
 202 as raw timestamps (i.e., in the form
 203 .Em sssssssss.uuuuuu ) .
 204 .It Fl r
 205 Same as
 206 .Fl R
 207 except the timestamps are dumped in human-readable format, similar
 208 to that used by
 209 .Xr date 1 .
 210 .It Fl t
 211 Same as
 212 .Fl R
 213 except the timestamps are dumped in
 214 .Nm
 215 format, i.e., in the
 216 .Em ymdhmsu
 217 format discussed above.
 218 .It Fl w Ar file
 219 Direct the output to
 220 .Ar file
 221 rather than
 222 .Pa stdout .
 223 .El
 224 .Sh SEE ALSO
 225 .Xr tcpdump 1
 226 .Sh AUTHORS
 227 .An Vern Paxson Aq vern@ee.lbl.gov ,
 228 of Lawrence Berkeley Laboratory, University of California, Berkeley, CA.
 229 .Sh BUGS
 230 An input filename that beings with a digit or a `+' can be confused
 231 with a start/end time.  Such filenames can be specified with a
 232 leading `./'; for example, specify the file `04Jul76.trace' as
 233 `./04Jul76.trace'.
 234 .Pp
 235 The
 236 .Nm
 237 utility cannot read its input from
 238 .Pa stdin ,
 239 since it uses random-access
 240 to rummage through its input files.
 241 .Pp
 242 The
 243 .Nm
 244 utility refuses to write to its output if it is a terminal
 245 (as indicated by
 246 .Xr isatty 3 ) .
 247 This is not a bug but a feature,
 248 to prevent it from spraying binary data to the user's terminal.
 249 Note that this means you must either redirect
 250 .Pa stdout
 251 or specify an
 252 output file via
 253 .Fl w .
 254 .Pp
 255 The
 256 .Nm
 257 utility will not work properly on
 258 .Xr tcpdump 1
 259 files spanning more than one year;
 260 with files containing portions of packets whose original length was
 261 more than 65,535 bytes; nor with files containing fewer than three packets.
 262 Such files result in
 263 the error message: `couldn't find final packet in file'.  These problems
 264 are due to the interpolation scheme used by
 265 .Nm
 266 to greatly speed up its processing when dealing with large trace files.
 267 Note that
 268 .Nm
 269 can efficiently extract slices from the middle of trace files of any
 270 size, and can also work with truncated trace files (i.e., the final packet
 271 in the file is only partially present, typically due to
 272 .Xr tcpdump 1
 273 being ungracefully killed).