Avoid collison with error(), clean up code a bit.

[tcpdump] / tcpdump.1.in

diff --git a/tcpdump.1.in b/tcpdump.1.in
index 956201054da365b7cfafc61c788032bc77886647..ebf50ab63d1e4cfc5202a0c970852179fc996b72 100644 (file)
--- a/tcpdump.1.in
+++ b/tcpdump.1.in
@@ -20,18 +20,21 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"

-.TH TCPDUMP 1  "26 February 2014"
+.TH TCPDUMP 1  "11 July 2014"

 .SH NAME
 tcpdump \- dump traffic on a network
 .SH SYNOPSIS
 .na
 .B tcpdump
 [
 .SH NAME
 tcpdump \- dump traffic on a network
 .SH SYNOPSIS
 .na
 .B tcpdump
 [

-.B \-AbdDefhHIJKlLnNOpqRStuUvxX
+.B \-AbdDefhHIJKlLnNOpqRStuUvxX#

 ] [
 .B \-B
 .I buffer_size
 ] [
 .B \-B
 .I buffer_size

-] [
+]
+.br
+.ti +8
+[

 .B \-c
 .I count
 ]
 .B \-c
 .I count
 ]


@@ -68,6 +71,9 @@ tcpdump \- dump traffic on a network
 .br
 .ti +8
 [
 .br
 .ti +8
 [

+.B \-\-number
+]
+[

 .B \-Q
 .I in|out|inout
 ]
 .B \-Q
 .I in|out|inout
 ]


@@ -120,6 +126,17 @@ tcpdump \- dump traffic on a network
 ]
 .ti +8
 [
 ]
 .ti +8
 [

+.BI \-\-time\-stamp\-precision= tstamp_precision
+]
+.ti +8
+[
+.B \-\-immediate\-mode
+]
+[
+.B \-\-version
+]
+.ti +8
+[

 .I expression
 ]
 .br
 .I expression
 ]
 .br


@@ -127,7 +144,9 @@ tcpdump \- dump traffic on a network
 .SH DESCRIPTION
 .LP
 \fITcpdump\fP prints out a description of the contents of packets on a
 .SH DESCRIPTION
 .LP
 \fITcpdump\fP prints out a description of the contents of packets on a

-network interface that match the boolean \fIexpression\fP.  It can also
+network interface that match the boolean \fIexpression\fP; the
+description is preceded by a time stamp, printed, by default, as hours,
+minutes, seconds, and fractions of a second since midnight.  It can also

 be run with the
 .B \-w
 flag, which causes it to save the packet data to a file for later
 be run with the
 .B \-w
 flag, which causes it to save the packet data to a file for later


@@ -191,7 +210,9 @@ your ``status'' character, typically control-T, although on some
 platforms, such as Mac OS X, the ``status'' character is not set by
 default, so you must set it with
 .BR stty (1)
 platforms, such as Mac OS X, the ``status'' character is not set by
 default, so you must set it with
 .BR stty (1)

-in order to use it) and will continue capturing packets.
+in order to use it) and will continue capturing packets. On platforms that
+do not support the SIGINFO signal, the same can be achieved by using the
+SIGUSR1 signal.

 .LP
 Reading packets from a network interface may require that you have
 special privileges; see the
 .LP
 Reading packets from a network interface may require that you have
 special privileges; see the


@@ -216,10 +237,10 @@ notation.
 Set the operating system capture buffer size to \fIbuffer_size\fP, in
 units of KiB (1024 bytes).
 .TP
 Set the operating system capture buffer size to \fIbuffer_size\fP, in
 units of KiB (1024 bytes).
 .TP

-.B \-c
+.BI \-c " count"

 Exit after receiving \fIcount\fP packets.
 .TP
 Exit after receiving \fIcount\fP packets.
 .TP

-.B \-C
+.BI \-C " file_size"

 Before writing a raw packet to a savefile, check whether the file is
 currently larger than \fIfile_size\fP and, if so, close the current
 savefile and open a new one.  Savefiles after the first savefile will
 Before writing a raw packet to a savefile, check whether the file is
 currently larger than \fIfile_size\fP and, if so, close the current
 savefile and open a new one.  Savefiles after the first savefile will


@@ -230,10 +251,6 @@ The units of \fIfile_size\fP are millions of bytes (1,000,000 bytes,
 not 1,048,576 bytes).
 .TP
 .B \-d
 not 1,048,576 bytes).
 .TP
 .B \-d

-.PD 0
-.TP
-.B \-\-list\-interfaces
-.PD

 Dump the compiled packet-matching code in a human readable form to
 standard output and stop.
 .TP
 Dump the compiled packet-matching code in a human readable form to
 standard output and stop.
 .TP


@@ -246,6 +263,10 @@ program fragment.
 Dump packet-matching code as decimal numbers (preceded with a count).
 .TP
 .B \-D
 Dump packet-matching code as decimal numbers (preceded with a count).
 .TP
 .B \-D

+.PD 0
+.TP
+.B \-\-list\-interfaces
+.PD

 Print the list of the network interfaces available on the system and on
 which
 .I tcpdump
 Print the list of the network interfaces available on the system and on
 which
 .I tcpdump


@@ -325,11 +346,11 @@ because the capture is being done on the Linux "any" interface, which
 can capture on more than one interface, this option will not work
 correctly.
 .TP
 can capture on more than one interface, this option will not work
 correctly.
 .TP

-.B \-F
+.BI \-F " file"

 Use \fIfile\fP as input for the filter expression.
 An additional expression given on the command line is ignored.
 .TP
 Use \fIfile\fP as input for the filter expression.
 An additional expression given on the command line is ignored.
 .TP

-.B \-G
+.BI \-G " rotate_seconds"

 If specified, rotates the dump file specified with the
 .B \-w
 option every \fIrotate_seconds\fP seconds.
 If specified, rotates the dump file specified with the
 .B \-w
 option every \fIrotate_seconds\fP seconds.


@@ -351,6 +372,10 @@ option, filenames will take the form of `\fIfile\fP<count>'.
 Print the tcpdump and libpcap version strings, print a usage message,
 and exit.
 .TP
 Print the tcpdump and libpcap version strings, print a usage message,
 and exit.
 .TP

+.B \-\-version
+.PD
+Print the tcpdump and libpcap version strings and exit.
+.TP

 .B \-H
 Attempt to detect 802.11s draft mesh headers.
 .TP
 .B \-H
 Attempt to detect 802.11s draft mesh headers.
 .TP


@@ -402,6 +427,13 @@ monitor mode will be shown; if
 is specified, only those link-layer types available when in monitor mode
 will be shown.
 .TP
 is specified, only those link-layer types available when in monitor mode
 will be shown.
 .TP

+.BI \-\-immediate\-mode
+Capture in "immediate mode".  In this mode, packets are delivered to
+tcpdump as soon as they arrive, rather than being buffered for
+efficiency.  This is the default when printing packets rather than
+saving packets to a ``savefile'' if the packets are being printed to a
+terminal rather than to a file or pipe.
+.TP

 .BI \-j " tstamp_type"
 .PD 0
 .TP
 .BI \-j " tstamp_type"
 .PD 0
 .TP


@@ -422,6 +454,25 @@ List the supported time stamp types for the interface and exit.  If the
 time stamp type cannot be set for the interface, no time stamp types are
 listed.
 .TP
 time stamp type cannot be set for the interface, no time stamp types are
 listed.
 .TP

+.BI \-\-time\-stamp\-precision= tstamp_precision
+When capturing, set the time stamp precision for the capture to
+\fItstamp_precision\fP.  Note that availability of high precision time
+stamps (nanoseconds) and their actual accuracy is platform and hardware
+dependent.  Also note that when writing captures made with nanosecond
+accuracy to a savefile, the time stamps are written with nanosecond
+resolution, and the file is written with a different magic number, to
+indicate that the time stamps are in seconds and nanoseconds; not all
+programs that read pcap savefiles will be able to read those captures.
+.LP
+When reading a savefile, convert time stamps to the precision specified
+by \fItimestamp_precision\fP, and display them with that resolution.  If
+the precision specified is less than the precision of time stamps in the
+file, the conversion will lose precision.
+.LP
+The supported values for \fItimestamp_precision\fP are \fBmicro\fP for
+microsecond resolution and \fBnano\fP for nanosecond resolution.  The
+default is microsecond resolution.
+.TP

 .B \-K
 .PD 0
 .TP
 .B \-K
 .PD 0
 .TP


@@ -483,12 +534,12 @@ and another set of data link types when in monitor mode (for example, it
 might support 802.11 headers, or 802.11 headers with radio information,
 only in monitor mode).
 .TP
 might support 802.11 headers, or 802.11 headers with radio information,
 only in monitor mode).
 .TP

-.B \-m
+.BI \-m " module"

 Load SMI MIB module definitions from file \fImodule\fR.
 This option
 can be used several times to load several MIB modules into \fItcpdump\fP.
 .TP
 Load SMI MIB module definitions from file \fImodule\fR.
 This option
 can be used several times to load several MIB modules into \fItcpdump\fP.
 .TP

-.B \-M
+.BI \-M " secret"

 Use \fIsecret\fP as a shared secret for validating the digests found in
 TCP segments with the TCP-MD5 option (RFC 2385), if present.
 .TP
 Use \fIsecret\fP as a shared secret for validating the digests found in
 TCP segments with the TCP-MD5 option (RFC 2385), if present.
 .TP


@@ -501,6 +552,13 @@ E.g.,
 if you give this flag then \fItcpdump\fP will print ``nic''
 instead of ``nic.ddn.mil''.
 .TP
 if you give this flag then \fItcpdump\fP will print ``nic''
 instead of ``nic.ddn.mil''.
 .TP

+.B \-#
+.PD 0
+.TP
+.B \-\-number
+.PD
+Print an optional packet number at the beginning of the line.
+.TP

 .B \-O
 .PD 0
 .TP
 .B \-O
 .PD 0
 .TP


@@ -541,10 +599,10 @@ If specified, \fItcpdump\fP will not print replay prevention field.
 Since there is no protocol version field in ESP/AH specification,
 \fItcpdump\fP cannot deduce the version of ESP/AH protocol.
 .TP
 Since there is no protocol version field in ESP/AH specification,
 \fItcpdump\fP cannot deduce the version of ESP/AH protocol.
 .TP

-.B \-r
+.BI \-r " file"

 Read packets from \fIfile\fR (which was created with the
 .B \-w
 Read packets from \fIfile\fR (which was created with the
 .B \-w

-option).
+option or by other tools that write pcap or pcap-ng files).

 Standard input is used if \fIfile\fR is ``-''.
 .TP
 .B \-S
 Standard input is used if \fIfile\fR is ``-''.
 .TP
 .B \-S


@@ -576,7 +634,7 @@ Setting
 for backwards compatibility with recent older versions of
 .IR tcpdump .
 .TP
 for backwards compatibility with recent older versions of
 .IR tcpdump .
 .TP

-.B \-T
+.BI \-T " type"

 Force packets selected by "\fIexpression\fP" to be interpreted the
 specified \fItype\fR.
 Currently known types are
 Force packets selected by "\fIexpression\fP" to be interpreted the
 specified \fItype\fR.
 Currently known types are


@@ -612,14 +670,16 @@ an encapsulated PGM packet.
 \fIDon't\fP print a timestamp on each dump line.
 .TP
 .B \-tt
 \fIDon't\fP print a timestamp on each dump line.
 .TP
 .B \-tt

-Print an unformatted timestamp on each dump line.
+Print the timestamp, as seconds since January 1, 1970, 00:00:00, UTC, and
+fractions of a second since that time, on each dump line.

 .TP
 .B \-ttt
 Print a delta (micro-second resolution) between current and previous line
 on each dump line.
 .TP
 .B \-tttt
 .TP
 .B \-ttt
 Print a delta (micro-second resolution) between current and previous line
 on each dump line.
 .TP
 .B \-tttt

-Print a timestamp in default format proceeded by date on each dump line.
+Print a timestamp, as hours, minutes, seconds, and fractions of a second
+since midnight, preceded by the date, on each dump line.

 .TP
 .B \-ttttt
 Print a delta (micro-second resolution) between current and first line
 .TP
 .B \-ttttt
 Print a delta (micro-second resolution) between current and first line


@@ -683,11 +743,11 @@ With
 .B \-X
 Telnet options are printed in hex as well.
 .TP
 .B \-X
 Telnet options are printed in hex as well.
 .TP

-.B \-V
+.BI \-V " file"

 Read a list of filenames from \fIfile\fR. Standard input is used
 if \fIfile\fR is ``-''.
 .TP
 Read a list of filenames from \fIfile\fR. Standard input is used
 if \fIfile\fR is ``-''.
 .TP

-.B \-w
+.BI \-w " file"

 Write the raw packets to \fIfile\fR rather than parsing and printing
 them out.
 They can later be printed with the \-r option.
 Write the raw packets to \fIfile\fR rather than parsing and printing
 them out.
 They can later be printed with the \-r option.


@@ -767,7 +827,7 @@ its link level header, in hex and ASCII.
 .PD
 Set the data link type to use while capturing packets to \fIdatalinktype\fP.
 .TP
 .PD
 Set the data link type to use while capturing packets to \fIdatalinktype\fP.
 .TP

-.B \-z
+.BI \-z " postrotate-command"

 Used in conjunction with the
 .B -C
 or
 Used in conjunction with the
 .B -C
 or


@@ -775,7 +835,7 @@ or
 options, this will make
 .I tcpdump
 run "
 options, this will make
 .I tcpdump
 run "

-.I command file
+.I postrotate-command file

 " where
 .I file
 is the savefile being closed after each rotation. For example, specifying
 " where
 .I file
 is the savefile being closed after each rotation. For example, specifying


@@ -792,10 +852,10 @@ different arguments, you can always write a shell script that will take the
 savefile name as the only argument, make the flags & arguments arrangements
 and execute the command that you want.
 .TP
 savefile name as the only argument, make the flags & arguments arrangements
 and execute the command that you want.
 .TP

-.B \-Z
+.BI \-Z " user"

 .PD 0
 .TP
 .PD 0
 .TP

-.B \-\-relinquish\-privileges
+.BI \-\-relinquish\-privileges= user

 .PD
 If
 .I tcpdump
 .PD
 If
 .I tcpdump


@@ -1822,11 +1882,15 @@ is the current clock time in the form
 .fi
 .RE
 and is as accurate as the kernel's clock.
 .fi
 .RE
 and is as accurate as the kernel's clock.

-The timestamp reflects the time the kernel first saw the packet.
-No attempt
-is made to account for the time lag between when the
-Ethernet interface removed the packet from the wire and when the kernel
-serviced the `new packet' interrupt.
+The timestamp reflects the time the kernel applied a time stamp to the packet.
+No attempt is made to account for the time lag between when the network
+interface finished receiving the packet from the network and when the
+kernel applied a time stamp to the packet; that time lag could include a
+delay between the time when the network interface finished receiving a
+packet from the network and the time when an interrupt was delivered to
+the kernel to get it to read the packet and a delay between the time
+when the kernel serviced the `new packet' interrupt and the time when it
+applied a time stamp to the packet.

 .SH "SEE ALSO"
 stty(1), pcap(3PCAP), bpf(4), nit(4P), pcap-savefile(@MAN_FILE_FORMATS@),
 pcap-filter(@MAN_MISC_INFO@), pcap-tstamp(@MAN_MISC_INFO@)
 .SH "SEE ALSO"
 stty(1), pcap(3PCAP), bpf(4), nit(4P), pcap-savefile(@MAN_FILE_FORMATS@),
 pcap-filter(@MAN_MISC_INFO@), pcap-tstamp(@MAN_MISC_INFO@)