add dumpcap manual page

svn path=/trunk/; revision=17237

3 files changed, 244 insertions, 2 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index ebe49fe5da..4ac5b3dbe3 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -127,6 +127,18 @@ ethereal-filter.pod: ethereal-filter.pod.template  ../tethereal
 	--noindex							\
 	$(srcdir)/text2pcap.pod > ../text2pcap.html
 
+../dumpcap.1: dumpcap.pod ../config.h
+	$(POD2MAN)					\
+	--center="The Ethereal Network Analyzer"	\
+	--release=$(VERSION)				\
+	$(srcdir)/dumpcap.pod > ../dumpcap.1
+
+../dumpcap.html: dumpcap.pod ../config.h
+	$(POD2HTML)                     \
+	--title="dumpcap - The Ethereal Network Analyzer $(VERSION)"	\
+	--noindex							\
+	$(srcdir)/dumpcap.pod > ../dumpcap.html
+
 CLEANFILES =		\
 	ethereal-filter.pod \
 	ethereal-tmp.pod \
@@ -144,6 +156,8 @@ CLEANFILES =		\
 	../tethereal.html	\
 	../text2pcap.1	\
 	../text2pcap.html	\
+	../dumpcap.1	\
+	../dumpcap.html	\
 	../idl2eth.1	\
 	../idl2eth.html
 
diff --git a/doc/Makefile.nmake b/doc/Makefile.nmake
index efdb784143..63b203031c 100644
--- a/doc/Makefile.nmake
+++ b/doc/Makefile.nmake
@@ -27,10 +27,10 @@
 include ../config.nmake
 
 doc: ethereal.html tethereal.html ethereal-filter.html capinfos.html \
-	editcap.html idl2eth.html mergecap.html text2pcap.html
+	editcap.html idl2eth.html mergecap.html text2pcap.html dumpcap.html
 
 man: ethereal.1 tethereal.1 ethereal-filter.4 capinfos.1 editcap.1 \
-	idl2eth.1 mergecap.1 text2pcap.1
+	idl2eth.1 mergecap.1 text2pcap.1 dumpcap.1
 
 ethereal-tmp.pod: ethereal.pod ../AUTHORS-SHORT-FORMAT
 	copy /B ethereal.pod + ..\AUTHORS-SHORT-FORMAT ethereal-tmp.pod
@@ -149,6 +149,18 @@ text2pcap.html: text2pcap.pod ../config.h
 	--noindex                                 \
 	text2pcap.pod > text2pcap.html
 
+dumpcap.1: dumpcap.pod ../config.h
+	$(POD2MAN)                      \
+	--center="The Ethereal Network Analyzer" \
+	--release=$(VERSION)			 \
+	dumpcap.pod > dumpcap.1
+
+dumpcap.html: dumpcap.pod ../config.h
+	$(POD2HTML)                     \
+	--title="dumpcap - The Ethereal Network Analyzer $(VERSION)" \
+	--noindex                                 \
+	dumpcap.pod > dumpcap.html
+
 clean:
 	rm -f ethereal.html ethereal.1 ethereal-tmp.pod
 	rm -f tethereal.html tethereal.1
@@ -158,6 +170,7 @@ clean:
 	rm -f idl2eth.html idl2eth.1
 	rm -f mergecap.html mergecap.1
 	rm -f text2pcap.html text2pcap.1
+	rm -f dumpcap.html dumpcap.1
 	rm -f pod2htm*
 
 distclean: clean
diff --git a/doc/dumpcap.pod b/doc/dumpcap.pod
new file mode 100644
index 0000000000..3ddfb24351
--- /dev/null
+++ b/doc/dumpcap.pod
@@ -0,0 +1,215 @@
+
+=head1 NAME
+
+dumpcap - Dump network traffic
+
+=head1 SYNOPSYS
+
+B<dumpcap>
+S<[ B<-a> E<lt>capture autostop conditionE<gt> ] ...>
+S<[ B<-b> E<lt>capture ring buffer optionE<gt>] ...>
+S<[ B<-B> E<lt>capture buffer size (Win32 only)E<gt> ] >
+S<[ B<-c> E<lt>capture packet countE<gt> ]>
+S<[ B<-D> ]>
+S<[ B<-f> E<lt>capture filterE<gt> ]>
+S<[ B<-h> ]>
+S<[ B<-i> E<lt>capture interfaceE<gt>|- ]> 
+S<[ B<-L> ]>
+S<[ B<-p> ]>
+S<[ B<-s> E<lt>capture snaplenE<gt> ]>
+S<[ B<-v> ]>
+S<[ B<-w> E<lt>outfileE<gt> ]>
+S<[ B<-y> E<lt>capture link typeE<gt> ]>
+
+=head1 DESCRIPTION
+
+B<Dumpcap> is a network traffic dump tool.  It lets you capture packet
+data from a live network and write the packets to a file.  B<Dumpcap>'s 
+native capture file format is B<libpcap> format, which is also the format 
+used by B<Ethereal>, B<tcpdump> and various other tools.  
+
+Without any options set it will 
+use the pcap library to capture traffic from the first available network 
+interface and writes the received raw packet data, along with the packets'
+time stamps into a libpcap file.
+
+If the B<-w> option is not specified, B<Dumpcap> writes to a newly 
+created libpcap file with a randomly chosen name. 
+If the B<-w> option is specified, B<Dumpcap> writes to the file
+specified by that option.
+
+Packet capturing is performed with the pcap library.  The capture filter
+syntax follows the rules of the pcap library.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -a  E<lt>capture autostop conditionE<gt>
+
+Specify a criterion that specifies when B<Dumpcap> is to stop writing
+to a capture file.  The criterion is of the form I<test>B<:>I<value>,
+where I<test> is one of:
+
+B<duration>:I<value> Stop writing to a capture file after I<value> seconds have elapsed.
+
+B<filesize>:I<value> Stop writing to a capture file after it reaches a size of I<value>
+kilobytes (where a kilobyte is 1024 bytes). If this option 
+is used together with the -b option, dumpcap will stop writing to the 
+current capture file and switch to the next one if filesize is reached.
+
+B<files>:I<value> Stop writing to capture files after I<value> number of files were written.
+
+=item -b  E<lt>capture ring buffer optionE<gt>
+
+Cause B<Dumpcap> to run in "multiple files" mode.  In "multiple files" mode, 
+B<Dumpcap> will write to several capture files. When the first capture file 
+fills up, B<Dumpcap> will switch writing to the next file and so on.
+
+The created filenames are based on the filename given with the B<-w> option, the number of 
+the file and on the creation date and time, 
+e.g. outfile_00001_20050604120117.pcap, outfile_00001_20050604120523.pcap, ...
+
+With the I<files> option it's also possible to form a "ring buffer". 
+This will fill up new files until the number of files specified, 
+at which point B<Dumpcap> will discard the data in the first file and start 
+writing to that file and so on. If the I<files> option is not set,
+new files filled up until one of the capture stop conditions match (or 
+until the disk if full).
+
+The criterion is of the form I<key>B<:>I<value>,
+where I<key> is one of:
+
+B<duration>:I<value> switch to the next file after I<value> seconds have 
+elapsed, even if the current file is not completely filled up.
+
+B<filesize>:I<value> switch to the next file after it reaches a size of 
+I<value> kilobytes (where a kilobyte is 1024 bytes). 
+
+B<files>:I<value> begin again with the first file after I<value> number of 
+files were written (form a ring buffer).
+
+=item -B  E<lt>capture buffer size (Win32 only)E<gt>
+
+Win32 only: set capture buffer size (in MB, default is 1MB). This is used by the
+the capture driver to buffer packet data until that data can be written to 
+disk. If you encounter packet drops while capturing, try to increase this size.
+
+=item -c  E<lt>capture packet countE<gt>
+
+Set the maximum number of packets to read when capturing live
+data.
+
+=item -D
+
+Print a list of the interfaces on which B<Dumpcap> can capture, and
+exit.  For each network interface, a number and an
+interface name, possibly followed by a text description of the
+interface, is printed.  The interface name or the number can be supplied
+to the B<-i> option to specify an interface on which to capture.
+
+This can be useful on systems that don't have a command to list them  
+(e.g., Windows systems, or UNIX systems lacking B<ifconfig -a>);
+the number can be useful on Windows 2000 and later systems, where the
+interface name is a somewhat complex string.
+
+Note that "can capture" means that B<Dumpcap> was able to open
+that device to do a live capture. Depending on your system you may need to 
+run dumpcap from an account with special privileges (for example, as root) 
+to be able to capture network traffic.
+If "B<dumpcap -D>" is not run from such an account, it will not list 
+any interfaces.
+
+=item -f  E<lt>capture filterE<gt>
+
+Set the capture filter expression.
+
+The entire filter expression must be specified as a single argument (which means 
+that if it contains spaces, it must be quoted).  
+
+=item -h
+
+Print the version and options and exits.
+
+=item -i  E<lt>capture interfaceE<gt>|-
+
+Set the name of the network interface or pipe to use for live packet
+capture. 
+
+Network interface names should match one of the names listed in
+"B<dumpcap -D>" (described above); a number, as reported by
+"B<dumpcap -D>", can also be used.  If you're using UNIX, "B<netstat
+-i>" or "B<ifconfig -a>" might also work to list interface names,
+although not all versions of UNIX support the B<-a> option to B<ifconfig>.
+
+If no interface is specified, B<Dumpcap> searches the list of
+interfaces, choosing the first non-loopback interface if there are any
+non-loopback interfaces, and choosing the first loopback interface if
+there are no non-loopback interfaces. If there are no interfaces at all,
+B<Dumpcap> reports an error and doesn't start the capture.
+
+Pipe names should be either the name of a FIFO (named pipe) or ``-'' to
+read data from the standard input.  Data read from pipes must be in
+standard libpcap format.
+
+Note: the Win32 version of B<Dumpcap> doesn't support capturing from
+pipes or stdin!
+
+=item -L
+
+List the data link types supported by the interface and exit. The reported
+link types can be used for the B<-y> option.
+
+=item -p
+
+I<Don't> put the interface into promiscuous mode.  Note that the
+interface might be in promiscuous mode for some other reason; hence,
+B<-p> cannot be used to ensure that the only traffic that is captured is
+traffic sent to or from the machine on which B<Dumpcap> is running,
+broadcast traffic, and multicast traffic to addresses received by that
+machine.
+
+=item -s  E<lt>capture snaplenE<gt>
+
+Set the default snapshot length to use when capturing live data. 
+No more than I<snaplen> bytes of each network packet will be read into
+memory, or saved to disk.
+
+=item -v
+
+Print the version and exit.
+
+=item -w  E<lt>outfileE<gt>
+
+Write raw packet data to I<outfile>.  
+
+NOTE: The usage of "-" for stdout is not allowed here!
+
+=item -y  E<lt>capture link typeE<gt>
+
+Set the data link type to use while capturing packets.  The values
+reported by B<-L> are the values that can be used.
+
+=back
+
+=head1 CAPTURE FILTER SYNTAX
+
+See the manual page of I<tcpdump(8)>.
+
+=head1 SEE ALSO
+
+I<ethereal(1)>, I<tethereal(1)>, I<editcap(1)>, I<tcpdump(8)>, I<pcap(3)>
+
+=head1 NOTES
+
+B<Dumpcap> 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 Ethereal project man pages are available at:
+http://www.ethereal.com/docs/man-pages
+
+=head1 AUTHORS
+
+B<Dumpcap> is derived from the B<Ethereal> capturing engine code; 
+see the list of
+authors in the B<Ethereal> man page for a list of authors of that code.