Alphabetical order, please.

[obnox/wireshark/wip.git] / doc / mergecap.pod

diff --git a/doc/mergecap.pod b/doc/mergecap.pod
index bda7b7895c5d0bd5ce85d05de2f61ad2b07ce9ac..44a6c214a48cca3b431d542148a73b380f20c749 100644 (file)
--- a/doc/mergecap.pod
+++ b/doc/mergecap.pod
@@ -1,17 +1,19 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

-mergecap - Merges two capture files into one
+mergecap - Merges two or more capture files into one

 
 

-=head1 SYNOPSYS
+=head1 SYNOPSIS

 
 B<mergecap>
 
 B<mergecap>

-S<[ B<-hva> ]>
-S<[ B<-s> I<snaplen> ]>
-S<[ B<-F> I<file format> ]>
-S<[ B<-T> I<encapsulation type> ]>
-S<B<-w> I<outfile>>
-I<infile>
+S<[ B<-a> ]>
+S<[ B<-F> E<lt>I<file format>E<gt> ]>
+S<[ B<-h> ]>
+S<[ B<-s> E<lt>I<snaplen>E<gt> ]>
+S<[ B<-T> E<lt>I<encapsulation type>E<gt> ]>
+S<[ B<-v> ]>
+S<B<-w> E<lt>I<outfile>E<gt>|->
+E<lt>I<infile>E<gt>

 I<...>
 
 =head1 DESCRIPTION
 I<...>
 
 =head1 DESCRIPTION


@@ -19,36 +21,24 @@ I<...>
 B<Mergecap> is a program that combines multiple saved capture files into
 a single output file specified by the B<-w> argument.  B<Mergecap> knows
 how to read B<libpcap> capture files, including those of B<tcpdump>,
 B<Mergecap> is a program that combines multiple saved capture files into
 a single output file specified by the B<-w> argument.  B<Mergecap> knows
 how to read B<libpcap> capture files, including those of B<tcpdump>,

-B<Ethereal>, and other tools that write captures in that format.  In
-addition, B<Mergecap> can read capture files from B<snoop> and
-B<atmsnoop>, Shomiti/Finisar B<Surveyor>, Novell B<LANalyzer>, Network
-General/Network Associates DOS-based B<Sniffer> (compressed or
-uncompressed), Microsoft B<Network Monitor>, AIX's B<iptrace>, Cinco
-Networks B<NetXRay>, Network Associates Windows-based B<Sniffer>, AG
-Group/WildPackets B<EtherPeek>/B<TokenPeek>/B<AiroPeek>, B<RADCOM>'s
-WAN/LAN analyzer, B<Lucent/Ascend> router debug output, HP-UX's
-B<nettl>, the dump output from B<Toshiba's> ISDN routers, the output
-from B<i4btrace> from the ISDN4BSD project, the output in B<IPLog>
-format from the Cisco Secure Intrusion Detection System, B<pppd logs>
-(pppdump format), the output from VMS's B<TCPIPtrace> utility, the text
-output from the B<DBS Etherwatch> VMS utility, traffic capture files
-from Visual Networks' Visual UpTime, and the output from B<CoSine> L2 
-debug.  There is no need to tell B<Mergecap> what type of file you are 
-reading; it will determine the file type by itself.  B<Mergecap> is 
-also capable of reading any of these file formats if they are compressed 
-using gzip.  B<Mergecap> recognizes this directly from the file; the 
-'.gz' extension is not required for this purpose.
-
-By default, it writes the capture file in B<libpcap> format, and writes
-all of the packets in both input capture files to the output file.  The
-B<-F> flag can be used to specify the format in which to write the
-capture file; it can write the file in B<libpcap> format (standard
-B<libpcap> format, a modified format used by some patched versions of
-B<libpcap>, the format used by Red Hat Linux 6.1, or the format used by
-SuSE Linux 6.3), B<snoop> format, uncompressed B<Sniffer> format,
-Microsoft B<Network Monitor> 1.x format, the format used by
-Windows-based versions of the B<Sniffer> software, and the format used
-by Visual Networks' software.
+B<Wireshark>, and other tools that write captures in that format.  
+
+By default, B<Mergecap> writes the capture file in B<libpcap> format, and writes
+all of the packets from the input capture files to the output file.  
+
+B<Mergecap> is able to detect, read and write the same capture files that 
+are supported by B<Wireshark>.
+The input files don't need a specific filename extension; the file 
+format and an optional gzip compression will be automatically detected.
+Near the beginning of the DESCRIPTION section of wireshark(1) or
+L<http://www.wireshark.org/docs/man-pages/wireshark.html>
+is a detailed description of the way B<Wireshark> handles this, which is
+the same way B<Mergecap> handles this.
+
+B<Mergecap> can write the file in several output formats.
+The B<-F> flag can be used to specify the format in which to write the
+capture file, B<mergecap -F> provides a list of the available output 
+formats.

 
 Packets from the input files are merged in chronological order based on
 each frame's timestamp, unless the B<-a> flag is specified.  B<Mergecap>
 
 Packets from the input files are merged in chronological order based on
 each frame's timestamp, unless the B<-a> flag is specified.  B<Mergecap>


@@ -57,89 +47,114 @@ chronological order.  When the B<-a> flag is specified, packets are
 copied directly from each input file to the output file, independent of
 each frame's timestamp.
 
 copied directly from each input file to the output file, independent of
 each frame's timestamp.
 

-If the B<-s> flag is used to specify a snapshot length, frames in the
-input file with more captured data than the specified snapshot length
-will have only the amount of data specified by the snapshot length
-written to the output file.  This may be useful if the program that is
-to read the output file cannot handle packets larger than a certain size
-(for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
-appear to reject Ethernet frames larger than the standard Ethernet MTU,
-making them incapable of handling gigabit Ethernet captures if jumbo
-frames were used).
-

 The output file frame encapsulation type is set to the type of the input
 The output file frame encapsulation type is set to the type of the input

-files, if all input files have the same type.  If not all of the input
+files if all input files have the same type.  If not all of the input

 files have the same frame encapsulation type, the output file type is
 set to WTAP_ENCAP_PER_PACKET.  Note that some capture file formats, most
 notably B<libpcap>, do not currently support WTAP_ENCAP_PER_PACKET.
 This combination will cause the output file creation to fail.
 
 files have the same frame encapsulation type, the output file type is
 set to WTAP_ENCAP_PER_PACKET.  Note that some capture file formats, most
 notably B<libpcap>, do not currently support WTAP_ENCAP_PER_PACKET.
 This combination will cause the output file creation to fail.
 

-If the B<-T> flag is used to specify a frame encapsulation type, the
-encapsulation type of the output capture file will be forced to the
-specified type, rather than being the type appropriate to the
-encapsulation type of the input capture files.  Note that this merely
-forces the encapsulation type of the output file to be the specified
-type; the packet headers of the packets will not be translated from the
-encapsulation type of the input capture file to the specified
-encapsulation type (for example, it will not translate an Ethernet
-capture to an FDDI capture if an Ethernet capture is read and 'B<-T
-fddi>' is specified).
-

 =head1 OPTIONS
 
 =over 4
 
 =head1 OPTIONS
 
 =over 4
 

-=item -w
-
-Sets the output filename.
-
-=item -F
-
-Sets the file format of the output capture file.
-
-=item -T
-
-Sets the packet encapsulation type of the output capture file.
-

 =item -a
 
 Causes the frame timestamps to be ignored, writing all packets from the
 first input file followed by all packets from the second input file.  By
 default, when B<-a> is not specified, the contents of the input files
 are merged in chronological order based on each frame's timestamp.
 =item -a
 
 Causes the frame timestamps to be ignored, writing all packets from the
 first input file followed by all packets from the second input file.  By
 default, when B<-a> is not specified, the contents of the input files
 are merged in chronological order based on each frame's timestamp.

+

 Note: when merging, B<mergecap> assumes that packets within a capture
 file are already in chronological order.
 
 Note: when merging, B<mergecap> assumes that packets within a capture
 file are already in chronological order.
 

+=item -F  E<lt>file formatE<gt>
+
+Sets the file format of the output capture file. B<Mergecap> can write 
+the file in several formats; B<mergecap -F> provides a list of the 
+available output formats. The default is to use the file format of the 
+first input file.
+
+=item -h
+
+Prints the version and options and exits.
+
+=item -s  E<lt>snaplenE<gt>
+
+Sets the snapshot length to use when writing the data.
+If the B<-s> flag is used to specify a snapshot length, frames in the
+input file with more captured data than the specified snapshot length
+will have only the amount of data specified by the snapshot length
+written to the output file.  This may be useful if the program that is
+to read the output file cannot handle packets larger than a certain size
+(for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
+appear to reject Ethernet frames larger than the standard Ethernet MTU,
+making them incapable of handling gigabit Ethernet captures if jumbo
+frames were used).
+

 =item -v
 
 Causes B<mergecap> to print a number of messages while it's working.
 
 =item -v
 
 Causes B<mergecap> to print a number of messages while it's working.
 

-=item -s
+=item -w  E<lt>outfileE<gt>|-

 
 

-Sets the snapshot length to use when writing the data.
+Sets the output filename. If the name is 'B<->', stdout will be used.
+This setting is mandatory.

 
 

-=item -h
+=item -T  E<lt>encapsulation typeE<gt>

 
 

-Prints the version and options and exits.
+Sets the packet encapsulation type of the output capture file.
+If the B<-T> flag is used to specify a frame encapsulation type, the
+encapsulation type of the output capture file will be forced to the
+specified type, rather than being the type appropriate to the
+encapsulation type of the input capture files.  
+
+Note that this merely
+forces the encapsulation type of the output file to be the specified
+type; the packet headers of the packets will not be translated from the
+encapsulation type of the input capture file to the specified
+encapsulation type (for example, it will not translate an Ethernet
+capture to an FDDI capture if an Ethernet capture is read and 'B<-T
+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

 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO
 

-I<tcpdump(8)>, I<pcap(3)>, I<ethereal(1)>, I<editcap(1)>
+tcpdump(8), pcap(3), wireshark(1), tshark(1), dumpcap(1), editcap(1),
+text2pcap(1)

 
 =head1 NOTES
 
 B<Mergecap> is based heavily upon B<editcap> by Richard Sharpe
 
 =head1 NOTES
 
 B<Mergecap> is based heavily upon B<editcap> by Richard Sharpe

-<sharpe@ns.aus.com> and Guy Harris <guy@alum.mit.edu>.
+<sharpe[AT]ns.aus.com> and Guy Harris <guy[AT]alum.mit.edu>.
+
+B<Mergecap> is part of the B<Wireshark> distribution.  The latest version
+of B<Wireshark> can be found at L<http://www.wireshark.org>.

 
 

-B<Mergecap> is part of the B<Ethereal> distribution.  The latest version
-of B<Ethereal> can be found at B<http://www.ethereal.com>.
+HTML versions of the Wireshark project man pages are available at:
+L<http://www.wireshark.org/docs/man-pages>.

 
 =head1 AUTHORS
 
   Original Author
   -------- ------
 
 =head1 AUTHORS
 
   Original Author
   -------- ------

-  Scott Renfro             <scott@renfro.org>
+  Scott Renfro             <scott[AT]renfro.org>

 
 
   Contributors
   ------------
 
 
   Contributors
   ------------

+  Bill Guyton              <guyton[AT]bguyton.com>