Add some info about extended value string to section 1.7.1
[obnox/wireshark/wip.git] / doc / capinfos.pod
index 19de7aef48ce78654a52287dedb8e43db3ffa6a7..33f58cf489f8b52a290b466f6be5951b8a195121 100644 (file)
@@ -3,32 +3,58 @@
 
 capinfos - Prints information about capture files
 
-=head1 SYNOPSYS
+=head1 SYNOPSIS
 
 B<capinfos>
-S<[ B<-t> ]>
-S<[ B<-E> ]>
+S<[ B<-a> ]>
+S<[ B<-A> ]>
+S<[ B<-b> ]>
+S<[ B<-B> ]>
 S<[ B<-c> ]>
-S<[ B<-s> ]>
+S<[ B<-C> ]>
 S<[ B<-d> ]>
-S<[ B<-u> ]>
-S<[ B<-a> ]>
 S<[ B<-e> ]>
-S<[ B<-y> ]>
+S<[ B<-E> ]>
+S<[ B<-h> ]>
+S<[ B<-H> ]>
 S<[ B<-i> ]>
+S<[ B<-l> ]>
+S<[ B<-L> ]>
+S<[ B<-m> ]>
+S<[ B<-N> ]>
+S<[ B<-o> ]>
+S<[ B<-q> ]>
+S<[ B<-Q> ]>
+S<[ B<-r> ]>
+S<[ B<-R> ]>
+S<[ B<-s> ]>
+S<[ B<-S> ]>
+S<[ B<-t> ]>
+S<[ B<-T> ]>
+S<[ B<-u> ]>
+S<[ B<-x> ]>
+S<[ B<-y> ]>
 S<[ B<-z> ]>
-S<[ B<-h> ]>
 E<lt>I<infile>E<gt>
 I<...>
 
 =head1 DESCRIPTION
 
 B<Capinfos> is a program that reads one or more capture files and
-returns some or all available statistics of each E<lt>I<infile>E<gt>.
+returns some or all available statistics (infos) of each E<lt>I<infile>E<gt>
+in one of two types of output formats: long or table.
+
+The long output is suitable for a human to read.  The table output
+is useful for generating a report that can be easily imported into
+a spreadsheet or database.
+
+The user specifies what type of output (long or table) and which 
+statistics to display by specifying flags (options) that corresponding 
+to the report type and desired infos.  If no options are specified, 
+B<Capinfos> will report all statistics available in "long" format.
 
-The user specifies which statistics to report by specifying flags
-corresponding to the statistic.  If no flags are specified, B<Capinfos>
-will report all statistics available.
+Options are processed from left to right order with later options 
+superceeding or adding to earlier options.
 
 B<Capinfos> is able to detect and read the same capture files that are
 supported by B<Wireshark>.
@@ -43,22 +69,57 @@ the same way B<Capinfos> handles this.
 
 =over 4
 
-=item -t
+=item -a
 
-Displays the capture type of the capture file.
+Displays the start time of the capture.  B<Capinfos> considers
+the earliest timestamp seen to be the start time, so the
+first packet in the capture is not necessarily the earliest -
+if packets exist "out-of-order", time-wise, in the capture,
+B<Capinfos> detects this.
 
-=item -E
+=item -
 
-Displays the per-file encapsulation of the capture file.
+Generate all infos. By default capinfos will display 
+all infos values for each input file, but enabling 
+any of the individual display infos options will 
+disable the generate all option.  
+
+=item -b 
+
+Separate infos with ASCII SPACE (0x20) characters.
+This option is only useful when generating a table 
+style report (-T).  The various info values will be 
+separated (delimited) from one another with a single 
+ASCII SPACE character.  
+
+NOTE: Since some of the header labels as well as some 
+of the value fields contain SPACE characters.  This 
+option is of limited value unless one of the quoting 
+options (-q or -Q) is also specified.
+
+=item -B 
+
+Separate the infos with ASCII TAB characters.  
+This option is only useful when generating a table 
+style report (-T).  The various info values will be 
+separated (delimited) from one another with a single 
+ASCII TAB character.  The TAB character is the default 
+delimiter when -T style report is enabled.
 
 =item -c
 
-Counts the number of packets in the capture file.
+Displays the number of packets in the capture file.
 
-=item -s
+=item -
 
-Displays the size of the file, in bytes.  This reports
-the size of the capture file itself.
+Cancel processing any additional files if and
+when capinfos should fail to open an input file.  
+By default capinfos will attempt to open each and 
+every file name argument.  
+
+Note: An error message will be written to stderr 
+whenever capinfos fails to open a file regardless
+of whether the -C option is specified or not.
 
 =item -d
 
@@ -70,20 +131,6 @@ For example, if a packet was originally 1514 bytes and only
 were captured with a snaplen or other slicing option),
 B<Capinfos> will consider the packet to have been 1514 bytes.
 
-=item -u
-
-Displays the capture duration, in seconds.  This is the
-difference in time between the earliest packet seen and
-latest packet seen.
-
-=item -a
-
-Displays the start time of the capture.  B<Capinfos> considers
-the earliest timestamp seen to be the start time, so the
-first packet in the capture is not necessarily the earliest -
-if packets exist "out-of-order", time-wise, in the capture,
-B<Capinfos> detects this.
-
 =item -e
 
 Displays the end time of the capture.  B<Capinfos> considers
@@ -92,27 +139,185 @@ last packet in the capture is not necessarily the latest -
 if packets exist "out-of-order", time-wise, in the capture,
 B<Capinfos> detects this.
 
-=item -y
+=item -E
+
+Displays the per-file encapsulation of the capture file.
 
-Displays the average data rate, in bytes
+=item -h
+
+Prints the help listing and exits.
+
+=item -H
+
+Displays the SHA1, RIPEMD160, and MD5 hashes for the file.
 
 =item -i
 
-Displays the average data rate, in bits
+Displays the average data rate, in bits/sec
 
-=item -z
+=item -
 
-displays the average packet size, in bytes
+Display the snaplen (if any) for a file.
+snaplen (if available) is determined from the capture file header
+and by looking for truncated records in the capture file.
 
-=item -h
+=item -o
 
-Prints the help listing and exits.
+Displays "True" if packets exist in strict chronological order 
+or "False" if one or more packets in the capture exists 
+"out-of-order" time-wise.
+
+=item -L 
+
+Generate long report.  Capinfos can generate two 
+different styles of reports.  The "long" report is 
+the default style of output and is suitable for a 
+human to use.
+
+=item -m 
+
+Separate the infos with comma (,) characters.  This option 
+is only useful when generating a table style report (-T).
+The various info values will be separated (delimited)
+from one another with a single comma "," character.
+
+=item -N 
+
+Do not quote the infos.  This option is only useful 
+when generating a table style report (-T).  Excluding 
+any quoting characters around the various values and 
+using a TAB delimiter produces a very "clean" table 
+report that is easily parsed with CLI tools.  By 
+default infos are B<NOT> quoted.
+
+=item -q 
+
+Quote infos with single quotes ('). This option is 
+only useful when generating a table style report (-T).
+When this option is enabled, each value will be
+encapsulated within a pair of single quote (') 
+characters.  This option (when used  with the -m 
+option) is useful for generating one type of CSV 
+style file report.
+
+=item -Q 
+
+Quote infos with double quotes (").  This option is 
+only useful when generating a table style report (-T).
+When this option is enabled, each value will be
+encapsulated within a pair of double quote (") 
+characters.  This option (when used with the -m 
+option) is useful for generating the most common
+type of CSV style file report.
+
+=item -r 
+
+Do not generate header record.  This option is only 
+useful when generating a table style report (-T).
+If this option is specified then B<no> header record will be 
+generated within the table report.
+
+=item -R 
+
+Generate header record.  This option is only useful 
+when generating a table style report (-T).  A header
+is generated by default.  A header record (if generated) 
+is the first line of data reported and includes labels 
+for all the columns included within the table report.  
+
+=item -s
+
+Displays the size of the file, in bytes.  This reports
+the size of the capture file itself.
+
+=item -S
+
+Display the start and end times as seconds since January
+1, 1970. Handy for synchronizing dumps using B<editcap -t>.
+
+=item -t
+
+Displays the capture type of the capture file.
+
+=item -T 
+
+Generate a table report. A table report is a text file
+that is suitable for importing into a spreadsheet or 
+database.  Capinfos can build a tab delimited text file 
+(the default) or several variations on Comma-separated 
+values (CSV) files.
+
+=item -u
+
+Displays the capture duration, in seconds.  This is the
+difference in time between the earliest packet seen and
+latest packet seen.
+
+=item -x
+
+Displays the average packet rate, in packets/sec
+
+=item -y
+
+Displays the average data rate, in bytes/sec
+
+=item -z
+
+Displays the average packet size, in bytes
 
 =back
 
+=head1 EXAMPLES
+
+To see a description of the capinfos options use:
+
+    capinfos -h
+
+To generate a long form report for the capture file 
+mycapture.pcap use:
+
+    capinfos mycapture.pcap 
+
+To generate a TAB delimited table form report for the capture 
+file mycapture.pcap use:
+
+    capinfos -T mycapture.pcap 
+
+To generate a CSV style table form report for the capture 
+file mycapture.pcap use:
+
+    capinfos -T -m -Q mycapture.pcap 
+
+or
+
+    capinfos -TmQ mycapture.pcap 
+
+
+To generate a TAB delimited table style report with just the 
+filenames, capture type, capture encapsulation type and packet 
+count for all the pcap files in the current directory use:
+
+    capinfos -T -t -E -c *.pcap
+
+or 
+  
+    capinfos -TtEs *.pcap
+
+Note: The ability to use of filename globbing characters are 
+a feature of *nix style command shells.  
+
+To generate a CSV delimited table style report of all infos 
+for all pcap files in the current directory and write it to 
+a text file called mycaptures.csv use:
+
+    capinfos -TmQ *.pcap >mycaptures.csv
+
+The resulting mycaptures.csv file can be easily imported 
+into spreadsheet applications.
+
 =head1 SEE ALSO
 
-tcpdump(8), pcap(3), wireshark(1)>, mergecap(1), editcap(1), tshark(1),
+tcpdump(8), pcap(3), wireshark(1), mergecap(1), editcap(1), tshark(1),
 dumpcap(1)
 
 =head1 NOTES
@@ -133,3 +338,4 @@ L<http://www.wireshark.org/docs/man-pages>.
   Contributors
   ------------
   Gerald Combs         <gerald[AT]wireshark.org>
+  Jim Young            <jyoung[AT]gsu.edu>