wslog: Add more documentation

debian/libwsutil0.symbols

@@ -235,6 +235,7 @@ libwsutil.so.0 libwsutil0 #MINVER#
  ws_log_level_is_active@Base 3.5.0
  ws_log_level_to_string@Base 3.5.0
  ws_log_parse_args@Base 3.5.0
+ ws_log_print_usage@Base 3.5.0
  ws_log_set_debug_filter@Base 3.5.0
  ws_log_set_domain_filter@Base 3.5.0
  ws_log_set_noisy_filter@Base 3.5.0

doc/tshark.pod

@@ -2073,6 +2073,25 @@ it will, on some OSes, assuming your environment is configured correctly,
 generate a core dump file.  This can be useful to developers attempting to
 troubleshoot a problem with a protocol dissector.
 
+=item WIRESHARK_LOG_LEVEL
+
+This environment variable controls the verbosity of diagnostic messages to
+the console. From less verbose to most verbose levels can be C<critical>,
+C<warning>, C<message>, C<info> or C<debug>. Levels above the current level
+are also active. Levels C<critical> and C<error> are always active.
+
+=item WIRESHARK_LOG_DOMAINS
+
+This environment variable selects with log domains are active. The filter is
+given as a case-insensitive comma separated list. If set only the included
+domains will be enabled. The default domain is always considered to be enabled.
+Domain filter lists can be preceded by '!' to invert the sense of the match.
+
+=item WIRESHARK_LOG_DEBUG
+
+List of domains with C<debug> log level. This sets the level of the listed
+log domains and takes precedence over the active domains filter.
+
 =back
 
 =head1 SEE ALSO

doc/wireshark.pod.template

@@ -2931,6 +2931,25 @@ that.  You must also specify an autostop condition, e.g.  B<-c> or B<-a
 duration:...>.  This means that you will not be able to see the results
 of the capture after it stops; it's primarily useful for testing.
 
+=item WIRESHARK_LOG_LEVEL
+
+This environment variable controls the verbosity of diagnostic messages to
+the console. From less verbose to most verbose levels can be C<critical>,
+C<warning>, C<message>, C<info> or C<debug>. Levels above the current level
+are also active. Levels C<critical> and C<error> are always active.
+
+=item WIRESHARK_LOG_DOMAINS
+
+This environment variable selects with log domains are active. The filter is
+given as a case-insensitive comma separated list. If set only the included
+domains will be enabled. The default domain is always considered to be enabled.
+Domain filter lists can be preceded by '!' to invert the sense of the match.
+
+=item WIRESHARK_LOG_DEBUG
+
+List of domains with C<debug> log level. This sets the level of the listed
+log domains and takes precedence over the active domains filter.
+
 =back
 
 =head1 SEE ALSO

docbook/wsdg_src/WSDG_chapter_sources.adoc

@@ -296,11 +296,12 @@ You can debug using command-line debuggers such as gdb, dbx, or lldb.
 If you prefer a graphic debugger, you can use an IDE or debugging frontend
 such as Qt Creator, CLion, or Eclipse.
 
-Additional traps can be set on GLib by setting the `G_DEBUG` environment variable:
+Additional traps can be set on Wireshark by setting the `WIRESHARK_LOG_FATAL`
+environment variable:
 
 [source,sh]
 ----
-$ G_DEBUG=fatal_criticals gdb wireshark
+$ WIRESHARK_LOG_FATAL=critical gdb wireshark
 ----
 
 If you're encountering memory safety bugs, you might want to build with

dumpcap.c

@@ -443,6 +443,9 @@ print_usage(FILE *output)
     fprintf(output, "                           add a capture comment to the output file\n");
     fprintf(output, "                           (only for pcapng)\n");
     fprintf(output, "\n");
+
+    ws_log_print_usage(output);
+
     fprintf(output, "Miscellaneous:\n");
     fprintf(output, "  -N <packet_limit>        maximum number of packets buffered within dumpcap\n");
     fprintf(output, "  -C <byte_limit>          maximum number of bytes used for buffering packets\n");

rawshark.c

@@ -201,6 +201,8 @@ print_usage(FILE *output)
     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");
 
+    ws_log_print_usage(output);
+
     fprintf(output, "\n");
     fprintf(output, "Miscellaneous:\n");
     fprintf(output, "  -h                       display this help and exit\n");

tfshark.c

@@ -212,6 +212,8 @@ print_usage(FILE *output)
   fprintf(output, "  -X <key>:<value>         eXtension options, see the man page for details\n");
   fprintf(output, "  -z <statistics>          various statistics, see the man page for details\n");
 
+  ws_log_print_usage(output);
+
   fprintf(output, "\n");
   fprintf(output, "Miscellaneous:\n");
   fprintf(output, "  -h                       display this help and exit\n");

tshark.c

@@ -479,6 +479,8 @@ print_usage(FILE *output)
   fprintf(output, "  --elastic-mapping-filter <protocols> If -G elastic-mapping is specified, put only the\n");
   fprintf(output, "                           specified protocols within the mapping file\n");
 
+  ws_log_print_usage(output);
+
   fprintf(output, "\n");
   fprintf(output, "Miscellaneous:\n");
   fprintf(output, "  -h, --help               display this help and exit\n");

ui/commandline.c

@@ -175,6 +175,8 @@ commandline_print_usage(gboolean for_help_option) {
     fprintf(output, "  --capture-comment <comment>\n");
     fprintf(output, "                           set the capture file comment, if supported\n");
 
+    ws_log_print_usage(output);
+
     fprintf(output, "\n");
     fprintf(output, "Miscellaneous:\n");
     fprintf(output, "  -h, --help               display this help and exit\n");

wsutil/wslog.c

@@ -682,3 +682,15 @@ void ws_log_add_custom_file(FILE *fp)
         }
         custom_log = fp;
 }
+
+
+void ws_log_print_usage(FILE *fp)
+{
+    fprintf(fp, "Diagnostic output:\n");
+    fprintf(fp, "  --log-level <level>      one of \"critical\", \"warning\", \"message\","
+                                            "\"info\", \"debug\" or \"noisy\"\n");
+    fprintf(fp, "  --log-domains <list>     comma separated list of the active log domains\n");
+    fprintf(fp, "  --log-file <file>        path of file to output messages to (in addition to stderr)\n");
+    fprintf(fp, "  --log-debug <list>       comma separated list of domains with \"debug\" level\n");
+    fprintf(fp, "  --log-noisy <list>       comma separated list of domains with \"noisy\" level\n");
+}

wsutil/wslog.h

@@ -16,6 +16,7 @@
 #include <stdarg.h>
 
 #ifndef WS_LOG_DOMAIN
+/* Should this be an error instead? */
 #define WS_LOG_DOMAIN LOG_DOMAIN_DEFAULT
 #endif
 
@@ -264,6 +265,10 @@ void ws_logv_full(const char *domain, enum ws_log_level level,
 WS_DLL_PUBLIC
 void ws_log_add_custom_file(FILE *fp);
 
+
+WS_DLL_PUBLIC
+void ws_log_print_usage(FILE *fp);
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */