Add an option to capinfos to print start and end times as seconds, which

makes time-shifting using editcap easier. Sort the flags in the capinfos
man page alphabetically to match the other man pages. Add a
time-shifting example to the mergecap man page.

svn path=/trunk/; revision=31905

3 files changed, 164 insertions, 115 deletions

diff --git a/capinfos.c b/capinfos.c
index 9dded9bda5..259a88f64a 100644
--- a/capinfos.c
+++ b/capinfos.c
@@ -130,6 +130,7 @@ static gboolean cap_data_size = TRUE;       /* Report packet byte size    */
 static gboolean cap_duration = TRUE;        /* Report capture duration    */
 static gboolean cap_start_time = TRUE;      /* Report capture start time  */
 static gboolean cap_end_time = TRUE;        /* Report capture end time    */
+static gboolean time_as_secs = FALSE;       /* Report time values as raw seconds */
 
 static gboolean cap_data_rate_byte = TRUE;  /* Report data rate bytes/sec */
 static gboolean cap_data_rate_bit = TRUE;   /* Report data rate bites/sec */
@@ -249,6 +250,28 @@ ctime_no_lf(const time_t* timer)
   return(time_string);
 }
 
+static gchar *
+time_string(const time_t *timer, capture_info *cf_info, gboolean want_lf)
+{
+  gchar *lf = want_lf ? "\n" : "";
+  static gchar time_string[15];
+
+  if (cf_info->packet_count > 0) {
+    if (time_as_secs) {
+      /* XXX - Would it be useful to show sub-second precision? */
+      g_snprintf(time_string, 15, "%lu%s", (unsigned long) *timer, lf);
+      return time_string;
+    } else if (want_lf) {
+      return ctime(timer);
+    } else {
+      return ctime_no_lf(timer);
+    }
+  }
+
+  g_snprintf(time_string, 15, "n/a%s", lf);
+  return time_string;
+}
+
 static double
 secs_nsecs(const struct wtap_nstime * nstime)
 {
@@ -282,8 +305,8 @@ print_stats(const gchar *filename, capture_info *cf_info)
   if (cap_file_size)      printf     ("File size:           %" G_GINT64_MODIFIER "d bytes\n", cf_info->filesize);
   if (cap_data_size)      printf     ("Data size:           %" G_GINT64_MODIFIER "u bytes\n", cf_info->packet_bytes);
   if (cap_duration)       print_value("Capture duration:    ", 0, " seconds",   cf_info->duration);
-  if (cap_start_time)     printf     ("Start time:          %s", (cf_info->packet_count>0) ? ctime (&start_time_t) : "n/a\n");
-  if (cap_end_time)       printf     ("End time:            %s", (cf_info->packet_count>0) ? ctime (&stop_time_t)  : "n/a\n");
+  if (cap_start_time)     printf     ("Start time:          %s", time_string(&start_time_t, cf_info, TRUE));
+  if (cap_end_time)       printf     ("End time:            %s", time_string(&stop_time_t, cf_info, TRUE));
   if (cap_data_rate_byte) print_value("Data byte rate:      ", 2, " bytes/sec",   cf_info->data_rate);
   if (cap_data_rate_bit)  print_value("Data bit rate:       ", 2, " bits/sec",    cf_info->data_rate*8);
   if (cap_packet_size)    printf     ("Average packet size: %.2f bytes\n",        cf_info->packet_size);
@@ -412,14 +435,14 @@ print_stats_table(const gchar *filename, capture_info *cf_info)
   if (cap_start_time) {
     putsep();
     putquote();
-    printf("%s", (cf_info->packet_count>0) ? ctime_no_lf (&start_time_t) : "n/a");
+    printf("%s", time_string(&start_time_t, cf_info, FALSE));
     putquote();
   }
 
   if (cap_end_time) {
     putsep();
     putquote();
-    printf("%s", (cf_info->packet_count>0) ? ctime_no_lf (&stop_time_t) : "n/a");
+    printf("%s", time_string(&stop_time_t, cf_info, FALSE));
     putquote();
   }
 
@@ -611,6 +634,7 @@ usage(gboolean is_error)
   fprintf(output, "  -u display the capture duration (in seconds)\n");
   fprintf(output, "  -a display the capture start time\n");
   fprintf(output, "  -e display the capture end time\n");
+  fprintf(output, "  -S display start and end times as seconds\n");
   fprintf(output, "\n");
   fprintf(output, "Statistic infos:\n");
   fprintf(output, "  -y display average data rate (in bytes/sec)\n");
@@ -710,7 +734,7 @@ main(int argc, char *argv[])
 
   /* Process the options */
 
-  while ((opt = getopt(argc, argv, "tEcs" FILE_HASH_OPT "duaeyizvhxCALTRrNqQBmb")) !=-1) {
+  while ((opt = getopt(argc, argv, "tEcs" FILE_HASH_OPT "duaeyizvhxCALTRrSNqQBmb")) !=-1) {
 
     switch (opt) {
 
@@ -754,6 +778,10 @@ main(int argc, char *argv[])
       cap_end_time = TRUE;
       break;
 
+    case 'S':
+      time_as_secs = TRUE;
+      break;
+
     case 'y':
       if (report_all_infos) disable_all_infos();
       cap_data_rate_byte = TRUE;
diff --git a/doc/capinfos.pod b/doc/capinfos.pod
index 6cfe5144d9..2c83016bda 100644
--- a/doc/capinfos.pod
+++ b/doc/capinfos.pod
@@ -6,32 +6,33 @@ capinfos - Prints information about capture files
 =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<-i> ]>
-S<[ B<-z> ]>
-S<[ B<-x> ]>
+S<[ B<-E> ]>
+S<[ B<-h> ]>
 S<[ B<-H> ]>
+S<[ B<-i> ]>
 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> ]>
+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> ]>
 E<lt>I<infile>E<gt>
 I<...>
 
@@ -66,22 +67,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 -A 
 
-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
 
 Displays the number of packets in the capture file.
 
-=item -s
+=item -C 
 
-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
 
@@ -93,20 +129,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
@@ -115,26 +137,22 @@ 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
-
-Displays the average data rate, in bytes/sec
-
-=item -i
-
-Displays the average data rate, in bits/sec
-
-=item -z
+=item -E
 
-Displays the average packet size, in bytes
+Displays the per-file encapsulation of the capture file.
 
-=item -x
+=item -h
 
-Displays the average packet rate, in packets/sec
+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/sec
+
 =item -L 
 
 Generate long report.  Capinfos can generate two 
@@ -142,38 +160,6 @@ 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 
@@ -181,19 +167,6 @@ 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 
@@ -223,27 +196,60 @@ characters.  This option (when used with the -m
 option) is useful for generating the most common
 type of CSV style file report.
 
-=item -h
+=item -r 
 
-Prints the help listing and exits.
+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 -C 
+=item -R 
 
-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.  
+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.  
 
-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 -s
 
-=item -A 
+Displays the size of the file, in bytes.  This reports
+the size of the capture file itself.
 
-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 -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
 
diff --git a/doc/mergecap.pod b/doc/mergecap.pod
index 5e8ab45448..b842584ba4 100644
--- a/doc/mergecap.pod
+++ b/doc/mergecap.pod
@@ -119,6 +119,21 @@ fddi>' is specified).
 
 =back
 
+=head1 EXAMPLES
+
+To merge two capture files together, 100 seconds apart use:
+
+    capinfos -aeS a.pcap b.pcap
+    
+(Let's suppose a.pcap starts at 1009932757 and b.pcap ends
+at 873660281. 1009932757 - 873660281 - 100 = 136272376
+seconds.)
+
+    editcap -t 136272376 b.pcap b-shifted.pcap
+    mergecap -w compare.pcap a.pcap b-shifted.pcap
+
+=back
+
 =head1 SEE ALSO
 
 tcpdump(8), pcap(3), wireshark(1), tshark(1), dumpcap(1), editcap(1),