From 87eca12c3853856b2e2e9d336e2d12158f91c4c6 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Sun, 26 Dec 2021 09:35:37 -0800 Subject: [PATCH] Docs: Document our diagnostic output options. Add docs/diagnostic-options.adoc, which is a snippet that documents our various --log-* options. Include it in the dumpcap, rawshark, and tshark man pages. Make the ws_log_print_usage output more consistent. --- doc/CMakeLists.txt | 4 ++++ doc/capinfos.adoc | 2 ++ doc/captype.adoc | 2 ++ doc/dftest.adoc | 2 ++ doc/diagnostic-options.adoc | 21 +++++++++++++++++++++ doc/dumpcap.adoc | 2 ++ doc/editcap.adoc | 2 ++ doc/mergecap.adoc | 2 ++ doc/randpkt.adoc | 2 ++ doc/rawshark.adoc | 2 ++ doc/reordercap.adoc | 2 ++ doc/text2pcap.adoc | 2 ++ doc/tshark.adoc | 2 ++ doc/wireshark.adoc | 2 ++ dumpcap.c | 1 + rawshark.c | 2 ++ tfshark.c | 3 ++- tshark.c | 3 ++- 18 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 doc/diagnostic-options.adoc diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 4c948bdf1b..d417d9a8c7 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -88,12 +88,15 @@ endif() set(BUNDLE_RESOURCE_SHARE_MAN1_FILES ${MAN1_INSTALL_FILES} PARENT_SCOPE) set(BUNDLE_RESOURCE_SHARE_MAN4_FILES ${MAN4_INSTALL_FILES} PARENT_SCOPE) +set(MAN_INCLUDES diagnostic-options.adoc) + if(ASCIIDOCTOR_FOUND) ASCIIDOCTOR2ROFFMAN(1 ${MAN1_SOURCE_FILES}) ASCIIDOCTOR2ROFFMAN(4 ${MAN4_SOURCE_FILES}) ASCIIDOCTOR2HTMLMAN(${MAN1_SOURCE_FILES} ${MAN4_SOURCE_FILES}) add_custom_target(manpages DEPENDS + ${MAN_INCLUDES} ${MAN1_INSTALL_FILES} ${MAN4_INSTALL_FILES} ) @@ -104,6 +107,7 @@ add_custom_target( docs ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT + ${MAN_INCLUDES} ${MAN1_INSTALL_FILES} ${MAN4_INSTALL_FILES} ${HTML_INSTALL_FILES} diff --git a/doc/capinfos.adoc b/doc/capinfos.adoc index 6477d5f418..16ed2e300a 100644 --- a/doc/capinfos.adoc +++ b/doc/capinfos.adoc @@ -401,6 +401,8 @@ Displays the average data rate, in bytes/sec Displays the average packet size, in bytes -- +include::diagnostic-options.adoc[] + == EXAMPLES To see a description of the options use: diff --git a/doc/captype.adoc b/doc/captype.adoc index 7b5e4ee492..4fd5eebde3 100644 --- a/doc/captype.adoc +++ b/doc/captype.adoc @@ -46,6 +46,8 @@ Print the version number and options and exit. Print the full version information and exit. -- +include::diagnostic-options.adoc[] + == SEE ALSO xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:mergecap.html[mergecap](1), xref:editcap.html[editcap](1), xref:tshark.html[tshark](1), diff --git a/doc/dftest.adoc b/doc/dftest.adoc index be12646dab..a148cbcdfe 100644 --- a/doc/dftest.adoc +++ b/doc/dftest.adoc @@ -29,6 +29,8 @@ filter:: The display filter expression. If needed it has to be quoted. -- +include::diagnostic-options.adoc[] + == EXAMPLES Show how the IP protocol is filtered: diff --git a/doc/diagnostic-options.adoc b/doc/diagnostic-options.adoc new file mode 100644 index 0000000000..bfca44b304 --- /dev/null +++ b/doc/diagnostic-options.adoc @@ -0,0 +1,21 @@ +== DIAGNOSTIC OPTIONS + +--log-level :: Set the active log level. +Supported levels in lowest to highest order are "noisy", "debug", "info", "message", "warning", "critical", and "error". +Messages at each level and higher will be printed, for example "warning" prints "warning", "critical", and "error" messages and "noisy" prints all messages. +Levels are case insensitive. + +--log-fatal :: Abort the program if any messages are logged at the specified level or higher. +For example, "warning" aborts on any "warning", "critical", or "error" messages. + +// XXX List avaliable domains if no list is provided? +--log-domains :: Only print messages for the specified log domains, e.g. "GUI,Epan,sshdump". +List of domains must be comma-separated. + +--log-debug :: Force the specified domains to log at the "debug" level. +List of domains must be comma-separated. + +--log-noisy :: Force the specified domains to log at the "debug" level. +List of domains must be comma-separated. + +--log-file :: Write log messages and stderr output to the specified file. diff --git a/doc/dumpcap.adoc b/doc/dumpcap.adoc index 39ce6976b2..3defdeb463 100644 --- a/doc/dumpcap.adoc +++ b/doc/dumpcap.adoc @@ -509,6 +509,8 @@ set, no time stamp types are listed. Change the interface's timestamp method. -- +include::diagnostic-options.adoc[] + == CAPTURE FILTER SYNTAX See the manual page of xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or, if that doesn't exist, xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8), diff --git a/doc/editcap.adoc b/doc/editcap.adoc index 3a6a8df693..b644e44669 100644 --- a/doc/editcap.adoc +++ b/doc/editcap.adoc @@ -460,6 +460,8 @@ file. Does not discard comments added by *--capture-comment* in the same command line. -- +include::diagnostic-options.adoc[] + == EXAMPLES To see more detailed description of the options use: diff --git a/doc/mergecap.adoc b/doc/mergecap.adoc index 01e39f2e2e..044e598dee 100644 --- a/doc/mergecap.adoc +++ b/doc/mergecap.adoc @@ -150,6 +150,8 @@ Sets the output filename. If the name is '*-*', stdout will be used. This setting is mandatory. -- +include::diagnostic-options.adoc[] + == EXAMPLES To merge two capture files together into a third capture file, in which diff --git a/doc/randpkt.adoc b/doc/randpkt.adoc index aa9faa8222..280c0b2357 100644 --- a/doc/randpkt.adoc +++ b/doc/randpkt.adoc @@ -92,6 +92,8 @@ Defines the type of packet to generate: usb-linux Universal Serial Bus with Linux specific header -- +include::diagnostic-options.adoc[] + == EXAMPLES To see a description of the randpkt options use: diff --git a/doc/rawshark.adoc b/doc/rawshark.adoc index ccc17a6e0a..e4d0644923 100644 --- a/doc/rawshark.adoc +++ b/doc/rawshark.adoc @@ -307,6 +307,8 @@ The default format is relative. Print the version and exit. -- +include::diagnostic-options.adoc[] + == READ FILTER SYNTAX For a complete table of protocol and protocol fields that are filterable diff --git a/doc/reordercap.adoc b/doc/reordercap.adoc index 57b0781575..623b26e995 100644 --- a/doc/reordercap.adoc +++ b/doc/reordercap.adoc @@ -54,6 +54,8 @@ file if it finds that the input file is already in order. Print the version and exit. -- +include::diagnostic-options.adoc[] + == SEE ALSO xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:editcap.html[editcap](1), xref:mergecap.html[mergecap](1), diff --git a/doc/text2pcap.adoc b/doc/text2pcap.adoc index f8189fb8b3..97c380649f 100644 --- a/doc/text2pcap.adoc +++ b/doc/text2pcap.adoc @@ -315,6 +315,8 @@ Example: __-6 fe80::202:b3ff:fe1e:8329,2001:0db8:85a3::8a2e:0370:7334__ to use fe80::202:b3ff:fe1e:8329 and 2001:0db8:85a3::8a2e:0370:7334 for all IP packets. -- +include::diagnostic-options.adoc[] + == SEE ALSO od(1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:mergecap.html[mergecap](1), diff --git a/doc/tshark.adoc b/doc/tshark.adoc index 29680f3361..e598c344a8 100644 --- a/doc/tshark.adoc +++ b/doc/tshark.adoc @@ -2392,6 +2392,8 @@ Enable dissection of heuristic protocol. Disable dissection of heuristic protocol. -- +include::diagnostic-options.adoc[] + == CAPTURE FILTER SYNTAX See the manual page of xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or, if that doesn't exist, xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8), diff --git a/doc/wireshark.adoc b/doc/wireshark.adoc index 55153420ee..4b8cc6e952 100644 --- a/doc/wireshark.adoc +++ b/doc/wireshark.adoc @@ -1089,6 +1089,8 @@ Show IEEE 802.11 network and station statistics. Show WSP packet counters. -- +include::diagnostic-options.adoc[] + == INTERFACE === MENU ITEMS diff --git a/dumpcap.c b/dumpcap.c index 3492283180..add3a89790 100644 --- a/dumpcap.c +++ b/dumpcap.c @@ -437,6 +437,7 @@ print_usage(FILE *output) fprintf(output, "\n"); ws_log_print_usage(output); + fprintf(output, "\n"); fprintf(output, "Miscellaneous:\n"); fprintf(output, " -N maximum number of packets buffered within dumpcap\n"); diff --git a/rawshark.c b/rawshark.c index 8ae7addc90..50e328e907 100644 --- a/rawshark.c +++ b/rawshark.c @@ -189,8 +189,10 @@ print_usage(FILE *output) fprintf(output, " -S format string for fields\n"); fprintf(output, " (%%D - name, %%S - stringval, %%N numval)\n"); fprintf(output, " -t ad|a|r|d|dd|e output format of time stamps (def: r: rel. to first)\n"); + fprintf(output, "\n"); ws_log_print_usage(output); + fprintf(output, "\n"); fprintf(output, "\n"); fprintf(output, "Miscellaneous:\n"); diff --git a/tfshark.c b/tfshark.c index 4c245d9dc7..b8803e098a 100644 --- a/tfshark.c +++ b/tfshark.c @@ -201,10 +201,11 @@ print_usage(FILE *output) fprintf(output, " -Q only log true errors to stderr (quieter than -q)\n"); fprintf(output, " -X : eXtension options, see the man page for details\n"); fprintf(output, " -z various statistics, see the man page for details\n"); + fprintf(output, "\n"); ws_log_print_usage(output); - fprintf(output, "\n"); + fprintf(output, "Miscellaneous:\n"); fprintf(output, " -h display this help and exit\n"); fprintf(output, " -v display version info and exit\n"); diff --git a/tshark.c b/tshark.c index 92bcd4ecf3..c8f5191d38 100644 --- a/tshark.c +++ b/tshark.c @@ -472,10 +472,11 @@ print_usage(FILE *output) fprintf(output, " values\n"); fprintf(output, " --elastic-mapping-filter If -G elastic-mapping is specified, put only the\n"); fprintf(output, " specified protocols within the mapping file\n"); + fprintf(output, "\n"); ws_log_print_usage(output); - fprintf(output, "\n"); + fprintf(output, "Miscellaneous:\n"); fprintf(output, " -h, --help display this help and exit\n"); fprintf(output, " -v, --version display version info and exit\n");