doc/man_pages/capinfos.adoc

   1 include::../attributes.adoc[]
   2 = capinfos(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 capinfos - Prints information about capture files
  11
  12 == SYNOPSIS
  13
  14 [manarg]
  15 *capinfos*
  16 [ *-a* ]
  17 [ *-A* ]
  18 [ *-b* ]
  19 [ *-B* ]
  20 [ *-c* ]
  21 [ *-C* ]
  22 [ *-d* ]
  23 [ *-D* ]
  24 [ *-e* ]
  25 [ *-E* ]
  26 [ *-F* ]
  27 [ *-h* ]
  28 [ *-H* ]
  29 [ *-i* ]
  30 [ *-I* ]
  31 [ *-k* ]
  32 [ *-K* ]
  33 [ *-l* ]
  34 [ *-L* ]
  35 [ *-m* ]
  36 [ *-M* ]
  37 [ *-n* ]
  38 [ *-N* ]
  39 [ *-o* ]
  40 [ *-p* ]
  41 [ *-P* ]
  42 [ *-q* ]
  43 [ *-Q* ]
  44 [ *-r* ]
  45 [ *-R* ]
  46 [ *-s* ]
  47 [ *-S* ]
  48 [ *-t* ]
  49 [ *-T* ]
  50 [ *-u* ]
  51 [ *-v* ]
  52 [ *-x* ]
  53 [ *-y* ]
  54 [ *-z* ]
  55 <__infile__>
  56 __...__
  57
  58 [manarg]
  59 *capinfos*
  60 *-h|--help*
  61
  62 [manarg]
  63 *capinfos*
  64 *-v|--version*
  65
  66 == DESCRIPTION
  67
  68 *Capinfos* is a program that reads one or more capture files and
  69 returns some or all available statistics (infos) of each <__infile__>
  70 in one of two types of output formats: long or table.
  71
  72 The long output is suitable for a human to read.  The table output
  73 is useful for generating a report that can be easily imported into
  74 a spreadsheet or database.
  75
  76 The user specifies what type of output (long or table) and which
  77 statistics to display by specifying flags (options) that corresponding
  78 to the report type and desired infos.  If no options are specified,
  79 *Capinfos* will report all statistics available in "long" format.
  80
  81 Options are processed from left to right order with later options
  82 superseding or adding to earlier options.
  83
  84 *Capinfos* is able to detect and read the same capture files that are
  85 supported by *Wireshark*.
  86 The input files don't need a specific filename extension; the file
  87 format and an optional gzip, zstd or lz4 compression will be automatically detected.
  88 Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or
  89 https://www.wireshark.org/docs/man-pages/wireshark.html
  90 is a detailed description of the way *Wireshark* handles this, which is
  91 the same way *Capinfos* handles this.
  92
  93 == OPTIONS
  94
  95 -a::
  96 Displays the timestamp of the earliest packet in the capture. The
  97 earliest packet in the capture is not necessarily the first packet in
  98 the capture - if packets exist "out-of-order", time-wise, in the
  99 capture, *Capinfos* detects this.
 100
 101 -A::
 102 Generate all infos. By default *Capinfos* will display
 103 all infos values for each input file, but enabling
 104 any of the individual display infos options will
 105 disable the generate all option.
 106
 107 -b::
 108 +
 109 --
 110 Separate infos with ASCII SPACE (0x20) characters.
 111 This option is only useful when generating a table
 112 style report (-T).  The various info values will be
 113 separated (delimited) from one another with a single
 114 ASCII SPACE character.
 115
 116 NOTE: Since some of the header labels as well as some
 117 of the value fields contain SPACE characters.  This
 118 option is of limited value unless one of the quoting
 119 options (-q or -Q) is also specified.
 120 --
 121
 122 -B::
 123 Separate the infos with ASCII TAB characters.
 124 This option is only useful when generating a table
 125 style report (-T).  The various info values will be
 126 separated (delimited) from one another with a single
 127 ASCII TAB character.  The TAB character is the default
 128 delimiter when -T style report is enabled.
 129
 130 -c::
 131 Displays the number of packets in the capture file.
 132
 133 -C::
 134 +
 135 --
 136 Cancel processing any additional files if and
 137 when *Capinfos* fails to open an input file
 138 or gets an error reading an input file.
 139 By default *Capinfos* will continue processing files
 140 even if it gets an error opening or reading a file.
 141
 142 Note: An error message will be written to stderr
 143 whenever *Capinfos* fails to open a file or gets
 144 an error reading from a file regardless whether
 145 the -C option is specified or not.
 146 Upon exit, *Capinfos* will return an error status
 147 if any errors occurred during processing.
 148 --
 149
 150 -d::
 151 Displays the total length of all packets in the file, in
 152 bytes.  This counts the size of the packets as they appeared
 153 in their original form, not as they appear in this file.
 154 For example, if a packet was originally 1514 bytes and only
 155 256 of those bytes were saved to the capture file (if packets
 156 were captured with a snaplen or other slicing option),
 157 *Capinfos* will consider the packet to have been 1514 bytes.
 158
 159 -D::
 160 Displays a count of the number of decryption secrets in the file. This information
 161 is not available in table format.
 162
 163 -e::
 164 Displays the timestamp of the latest packet in the capture. The latest
 165 packet in the capture is not necessarily the last packet in the capture
 166 - if packets exist "out-of-order", time-wise, in the capture, *Capinfos*
 167 detects this.
 168
 169 -E::
 170 Displays the per-file encapsulation of the capture file.
 171
 172 -F::
 173 Displays additional capture file information.
 174
 175 -h|--help::
 176 Print the version number and options and exit.
 177
 178 -H::
 179 Displays the SHA256 and SHA1 hashes for the file.
 180 SHA1 output may be removed in the future.
 181
 182 -i::
 183 Displays the average data rate, in bits/sec
 184
 185 -I::
 186 Displays detailed capture file interface information. This information
 187 is not available in table format.
 188
 189 -k::
 190 Displays the capture comment. For pcapng files, this is the comment from the
 191 section header block.
 192
 193 -K::
 194 Use this option to suppress printing capture comments.  By default capture
 195 comments are enabled.  Capture comments are relatively freeform and might
 196 contain embedded new-line characters and/or other delimiting characters
 197 making it harder for a human or machine to easily parse the *Capinfos* output.
 198 Excluding capture comments can aid in post-processing of output.
 199
 200 -l::
 201 Display the snaplen (if any) for a file.
 202 snaplen (if available) is determined from the capture file header
 203 and by looking for truncated records in the capture file.
 204
 205 -L::
 206 Generate long report.  *Capinfos* can generate two
 207 different styles of reports.  The "long" report is
 208 the default style of output and is suitable for a
 209 human to use.
 210
 211 -m::
 212 Separate the infos with comma (,) characters.  This option
 213 is only useful when generating a table style report (-T).
 214 The various info values will be separated (delimited)
 215 from one another with a single comma "," character.
 216
 217 -M::
 218 Print raw (machine readable) values in long reports.
 219 By default *Capinfos* prints numeric values with human-readable SI
 220 suffixes, and shows human-readable file type and encapsulation.
 221 Table reports (-T) always print raw values.
 222
 223 -n::
 224 Displays a count of the number of resolved IPv4 addresses and a count of
 225 the number of resolved IPv6 addresses in the file. This information
 226 is not available in table format.
 227
 228 -N::
 229 Do not quote the infos.  This option is only useful
 230 when generating a table style report (-T).  Excluding
 231 any quoting characters around the various values and
 232 using a TAB delimiter produces a very "clean" table
 233 report that is easily parsed with CLI tools.  By
 234 default infos are *NOT* quoted.
 235
 236 -o::
 237 Displays "True" if packets exist in strict chronological order
 238 or "False" if one or more packets in the capture exists
 239 "out-of-order" time-wise.
 240
 241 -p::
 242 Display individual packet comments.  It is recommended
 243 to print raw values (-M) when using this option as
 244 packet comments may include newlines and other special
 245 characters.
 246
 247 -P::
 248 Disable displaying individual packet comments.
 249
 250 -q::
 251 Quote infos with single quotes ('). This option is
 252 only useful when generating a table style report (-T).
 253 When this option is enabled, each value will be
 254 encapsulated within a pair of single quote (')
 255 characters.  This option (when used  with the -m
 256 option) is useful for generating one type of CSV
 257 style file report.
 258
 259 -Q::
 260 Quote infos with double quotes (").  This option is
 261 only useful when generating a table style report (-T).
 262 When this option is enabled, each value will be
 263 encapsulated within a pair of double quote (")
 264 characters.  This option (when used with the -m
 265 option) is useful for generating the most common
 266 type of CSV style file report.
 267
 268 -r::
 269 Do not generate header record.  This option is only
 270 useful when generating a table style report (-T).
 271 If this option is specified then *no* header record will be
 272 generated within the table report.
 273
 274 -R::
 275 Generate header record.  This option is only useful
 276 when generating a table style report (-T).  A header
 277 is generated by default.  A header record (if generated)
 278 is the first line of data reported and includes labels
 279 for all the columns included within the table report.
 280
 281 -s::
 282 Displays the size of the file, in bytes.  This reports
 283 the size of the capture file itself.
 284
 285 -S::
 286 Display the earliest and latest packet timestamps as seconds since
 287 January 1, 1970. Handy for synchronizing dumps using *editcap -t*.
 288
 289 -t::
 290 Displays the capture type of the capture file.
 291
 292 -T::
 293 Generate a table report. A table report is a text file
 294 that is suitable for importing into a spreadsheet or
 295 database.  *Capinfos* can build a tab delimited text file
 296 (the default) or several variations on Comma-separated
 297 values (CSV) files.
 298
 299 -u::
 300 Displays the capture duration, in seconds.  This is the
 301 difference in time between the earliest packet seen and
 302 latest packet seen.
 303
 304 -v|--version::
 305 Print the full version information and exit.
 306
 307 -x::
 308 Displays the average packet rate, in packets/sec
 309
 310 -y::
 311 Displays the average data rate, in bytes/sec
 312
 313 -z::
 314 Displays the average packet size, in bytes
 315
 316 include::diagnostic-options.adoc[]
 317
 318 == EXAMPLES
 319
 320 To see a description of the options use:
 321
 322     capinfos -h
 323
 324 To generate a long form report for the capture file
 325 mycapture.pcap use:
 326
 327     capinfos mycapture.pcap
 328
 329 To generate a TAB delimited table form report for the capture
 330 file mycapture.pcap use:
 331
 332     capinfos -T mycapture.pcap
 333
 334 To generate a CSV style table form report for the capture
 335 file mycapture.pcap use:
 336
 337     capinfos -T -m -Q mycapture.pcap
 338
 339 or
 340
 341     capinfos -TmQ mycapture.pcap
 342
 343 To generate a TAB delimited table style report with just the
 344 filenames, capture type, capture encapsulation type and packet
 345 count for all the pcap files in the current directory use:
 346
 347     capinfos -T -t -E -c *.pcap
 348
 349 or
 350
 351     capinfos -TtEc *.pcap
 352
 353 Note: The ability to use of filename globbing characters are
 354 a feature of *nix style command shells.
 355
 356 To generate a CSV delimited table style report of all infos
 357 for all pcap files in the current directory and write it to
 358 a text file called mycaptures.csv use:
 359
 360     capinfos -TmQ *.pcap >mycaptures.csv
 361
 362 The resulting mycaptures.csv file can be easily imported
 363 into spreadsheet applications.
 364
 365 == SEE ALSO
 366
 367 xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:mergecap.html[mergecap](1), xref:editcap.html[editcap](1), xref:tshark.html[tshark](1),
 368 xref:dumpcap.html[dumpcap](1), xref:captype.html[captype](1), xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8)
 369
 370 == NOTES
 371
 372 This is the manual page for *Capinfos* {wireshark-version}.
 373 *Capinfos* is part of the *Wireshark* distribution.
 374 The latest version of *Wireshark* can be found at https://www.wireshark.org.
 375
 376 HTML versions of the Wireshark project man pages are available at
 377 https://www.wireshark.org/docs/man-pages.
 378
 379 == AUTHORS
 380
 381 .Original Author
 382 [%hardbreaks]
 383 Ian Schorr <ian[AT]ianschorr.com>
 384
 385 .Contributors
 386 [%hardbreaks]
 387 Gerald Combs <gerald[AT]wireshark.org>
 388 Jim Young <jyoung[AT]gsu.edu>