From Jim Young:

The ability to continue processing additional files if and when 
wtap_open_offline() should fail.  A new -C option reverts to capinfos' 
original behavior which is to cancel any further file processing at 
first file open failure.

Change the behavior of how the default display of all infos is initiated.
This gets rid of a special post getopt() argument count test.

Add new table output format (with related options). This feature allows 
outputting the various infos into a tab delimited text file, or to a comma 
separated variables file (*.csv) instead of the original "long" format.

svn path=/trunk/; revision=30956

1 files changed, 185 insertions, 6 deletions

diff --git a/doc/capinfos.pod b/doc/capinfos.pod
index 4af4c39426..ef15aaeb33 100644
--- a/doc/capinfos.pod
+++ b/doc/capinfos.pod
@@ -17,19 +17,39 @@ S<[ B<-e> ]>
 S<[ B<-y> ]>
 S<[ B<-i> ]>
 S<[ B<-z> ]>
-S<[ B<-x> ]>
+S<[ B<-L> ]>
+S<[ B<-T> ]>
+S<[ B<-R> ]>
+S<[ B<-r> ]>
+S<[ B<-B> ]>
+S<[ B<-m> ]>
+S<[ B<-b> ]>
+S<[ B<-N> ]>
+S<[ B<-q> ]>
+S<[ B<-Q> ]>
 S<[ B<-h> ]>
+S<[ B<-C> ]>
+S<[ B<-A> ]>
 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 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.
+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.
+
+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>.
@@ -54,7 +74,7 @@ Displays the per-file encapsulation of the capture file.
 
 =item -c
 
-Counts the number of packets in the capture file.
+Displays the number of packets in the capture file.
 
 =item -s
 
@@ -109,12 +129,170 @@ displays the average packet size, in bytes
 
 displays the average packet rate, in packets/sec
 
+=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 -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 -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 -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 -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 -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 -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 -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 -h
 
 Prints the help listing and exits.
 
+=item -C 
+
+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 -A 
+
+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.  
+
+
 =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),
@@ -138,3 +316,4 @@ L<http://www.wireshark.org/docs/man-pages>.
   Contributors
   ------------
   Gerald Combs         <gerald[AT]wireshark.org>
+  Jim Young            <jyoung[AT]gsu.edu>