Wireshark 4.7.0
The Wireshark network protocol analyzer
Loading...
Searching...
No Matches
wslog.h
Go to the documentation of this file.
1
12#ifndef __WSLOG_H__
13#define __WSLOG_H__
14
15#include <inttypes.h>
16#include <stdbool.h>
17#include <stdio.h>
18#include <stdarg.h>
19#include <time.h>
20#include <glib.h>
21
22#include <ws_symbol_export.h>
23#include <ws_attributes.h>
24#include <ws_log_defs.h>
25#include <ws_posix_compat.h>
26#include "ws_getopt.h"
27
28#ifdef WS_LOG_DOMAIN
29#define _LOG_DOMAIN WS_LOG_DOMAIN
30#else
31#define _LOG_DOMAIN ""
32#endif
33
34#ifdef WS_DEBUG
35#define _LOG_DEBUG_ENABLED true
36#else
37#define _LOG_DEBUG_ENABLED false
38#endif
39
40/*
41 * Define the macro WS_LOG_DOMAIN *before* including this header,
42 * for example:
43 * #define WS_LOG_DOMAIN LOG_DOMAIN_MAIN
44 */
45
46#ifdef __cplusplus
47extern "C" {
48#endif /* __cplusplus */
49
50/*
51 * Console open preference is stored in the Windows registry.
52 * HKEY_CURRENT_USER\Software\Wireshark\ConsoleOpen
53 */
54#define LOG_HKCU_CONSOLE_OPEN "ConsoleOpen"
55
66
67
68WSUTIL_EXPORT
69ws_log_console_open_pref ws_log_console_open;
70
77typedef struct {
78 struct tm tstamp_secs;
79 long nanosecs;
80 intmax_t pid;
82
84typedef void (ws_log_writer_cb)(const char *domain, enum ws_log_level level,
85 const char *file, long line, const char *func,
86 const char *fatal_msg, ws_log_manifest_t *mft,
87 const char *user_format, va_list user_ap,
88 void *user_data);
89
90
92typedef void (ws_log_writer_free_data_cb)(void *user_data);
93
107WS_DLL_PUBLIC
108void ws_log_file_writer(FILE *fp, const char *domain, enum ws_log_level level,
109 const char *file, long line, const char *func,
111 const char *user_format, va_list user_ap);
112
125WS_DLL_PUBLIC
126void ws_log_console_writer(const char *domain, enum ws_log_level level,
127 const char *file, long line, const char *func,
129 const char *user_format, va_list user_ap);
130
131
142WS_DLL_PUBLIC
143void ws_log_console_writer_set_use_stdout(bool use_stdout);
144
145
152WS_DLL_PUBLIC
153WS_RETNONNULL
154const char *ws_log_level_to_string(enum ws_log_level level);
155
156
167WS_DLL_PUBLIC
168bool ws_log_msg_is_active(const char *domain, enum ws_log_level level);
169
170
178WS_DLL_PUBLIC
179enum ws_log_level ws_log_get_level(void);
180
181
191WS_DLL_PUBLIC
192enum ws_log_level ws_log_set_level(enum ws_log_level level);
193
194
205WS_DLL_PUBLIC
206enum ws_log_level ws_log_set_level_str(const char *str_level);
207
208
219WS_DLL_PUBLIC
220void ws_log_set_domain_filter(const char *domain_filter);
221
230WS_DLL_PUBLIC
231void ws_log_set_fatal_domain_filter(const char *domain_filter);
232
233
244WS_DLL_PUBLIC
245void ws_log_set_debug_filter(const char *str_filter);
246
247
255WS_DLL_PUBLIC
256void ws_log_set_noisy_filter(const char *str_filter);
257
258
269WS_DLL_PUBLIC
270enum ws_log_level ws_log_set_fatal_level(enum ws_log_level level);
271
272
282WS_DLL_PUBLIC
283enum ws_log_level ws_log_set_fatal_level_str(const char *str_level);
284
285
293WS_DLL_PUBLIC
295
296
308WS_DLL_PUBLIC
310 void *user_data,
311 ws_log_writer_free_data_cb *free_user_data);
312
313
314#define LOG_ARGS_NOEXIT -1
315
316#define LONGOPT_WSLOG_LOG_LEVEL LONGOPT_BASE_WSLOG+1
317#define LONGOPT_WSLOG_LOG_DOMAIN LONGOPT_BASE_WSLOG+2
318#define LONGOPT_WSLOG_LOG_FILE LONGOPT_BASE_WSLOG+3
319#define LONGOPT_WSLOG_LOG_FATAL LONGOPT_BASE_WSLOG+4
320#define LONGOPT_WSLOG_LOG_FATAL_DOMAIN LONGOPT_BASE_WSLOG+5
321#define LONGOPT_WSLOG_LOG_DEBUG LONGOPT_BASE_WSLOG+6
322#define LONGOPT_WSLOG_LOG_NOISY LONGOPT_BASE_WSLOG+7
323
326#define LONGOPT_WSLOG \
327 {"log-level", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_LEVEL}, \
328 {"log-domain", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_DOMAIN}, \
329 /* Alias "domain" and "domains". */ \
330 {"log-domains", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_DOMAIN}, \
331 {"log-file", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FILE}, \
332 {"log-fatal", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FATAL}, \
333 /* Alias "domain" and "domains". */ \
334 {"log-fatal-domain", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FATAL_DOMAIN}, \
335 {"log-fatal-domains", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FATAL_DOMAIN}, \
336 {"log-debug", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_DEBUG}, \
337 {"log-noisy", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_NOISY},
338
354WS_DLL_PUBLIC
355int ws_log_parse_args(int *argc_ptr, char *argv[],
356 const char* optstring, const struct ws_option* long_options,
357 void (*vcmdarg_err)(const char *, va_list ap),
358 int exit_failure);
359
360
370WS_DLL_PUBLIC
371bool ws_log_is_wslog_arg(int arg);
372
373
383WS_DLL_PUBLIC
384void ws_log_init(void (*vcmdarg_err)(const char *, va_list ap));
385
386
396WS_DLL_PUBLIC
398 void (*vcmdarg_err)(const char *, va_list ap));
399
400
413WS_DLL_PUBLIC
415 void *user_data,
416 ws_log_writer_free_data_cb *free_user_data,
417 void (*vcmdarg_err)(const char *, va_list ap));
418
419
432WS_DLL_PUBLIC
433void ws_log(const char *domain, enum ws_log_level level,
434 const char *format, ...) G_GNUC_PRINTF(3,4);
435
436
448WS_DLL_PUBLIC
449void ws_logv(const char *domain, enum ws_log_level level,
450 const char *format, va_list ap);
451
452
469WS_DLL_PUBLIC
470void ws_log_full(const char *domain, enum ws_log_level level,
471 const char *file, long line, const char *func,
472 const char *format, ...) G_GNUC_PRINTF(6,7);
473
474
490WS_DLL_PUBLIC
491void ws_logv_full(const char *domain, enum ws_log_level level,
492 const char *file, long line, const char *func,
493 const char *format, va_list ap);
494
495
511WS_DLL_PUBLIC
512WS_NORETURN
513void ws_log_fatal_full(const char *domain, enum ws_log_level level,
514 const char *file, long line, const char *func,
515 const char *format, ...) G_GNUC_PRINTF(6,7);
516
517
518/*
519 * The if condition avoids -Wunused warnings for variables used only with
520 * WS_DEBUG, typically inside a ws_debug() call. The compiler will
521 * optimize away the dead execution branch.
522 */
523#define _LOG_IF_ACTIVE(active, level, file, line, func, ...) \
524 do { \
525 if (active) { \
526 ws_log_full(_LOG_DOMAIN, level, \
527 file, line, func, \
528 __VA_ARGS__); \
529 } \
530 } while (0)
531
532#define _LOG_FULL(active, level, ...) \
533 _LOG_IF_ACTIVE(active, level, __FILE__, __LINE__, __func__, __VA_ARGS__)
534
535#define _LOG_SIMPLE(active, level, ...) \
536 _LOG_IF_ACTIVE(active, level, NULL, -1, NULL, __VA_ARGS__)
537
547#define ws_error(...) \
548 ws_log_fatal_full(_LOG_DOMAIN, LOG_LEVEL_ERROR, \
549 __FILE__, __LINE__, __func__, __VA_ARGS__)
550
561#define ws_critical(...) \
562 _LOG_FULL(true, LOG_LEVEL_CRITICAL, __VA_ARGS__)
563
574#define ws_warning(...) \
575 _LOG_FULL(true, LOG_LEVEL_WARNING, __VA_ARGS__)
576
587#define ws_message(...) \
588 _LOG_SIMPLE(true, LOG_LEVEL_MESSAGE, __VA_ARGS__)
589
600#define ws_info(...) \
601 _LOG_SIMPLE(true, LOG_LEVEL_INFO, __VA_ARGS__)
602
603
614#define ws_debug(...) \
615 _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_DEBUG, __VA_ARGS__)
616
628#define ws_noisy(...) \
629 _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_NOISY, __VA_ARGS__)
630
631
641#define WS_DEBUG_HERE(...) \
642 _LOG_FULL(true, LOG_LEVEL_ECHO, __VA_ARGS__)
643
651#define WS_NOT_IMPLEMENTED() \
652 ws_error("Not implemented yet")
653
654
671WS_DLL_PUBLIC
672void ws_log_utf8_full(const char *domain, enum ws_log_level level,
673 const char *file, long line, const char *func,
674 const char *string, ssize_t length, const char *endptr);
675
676
689#define ws_log_utf8(str, len, endptr) \
690 do { \
691 if (_LOG_DEBUG_ENABLED) { \
692 ws_log_utf8_full(LOG_DOMAIN_UTF_8, LOG_LEVEL_DEBUG, \
693 __FILE__, __LINE__, __func__, \
694 str, len, endptr); \
695 } \
696 } while (0)
697
698
716WS_DLL_PUBLIC
717void ws_log_buffer_full(const char *domain, enum ws_log_level level,
718 const char *file, long line, const char *func,
719 const uint8_t *buffer, size_t size,
720 size_t max_bytes_len, const char *msg);
721
734#define ws_log_buffer(buf, size, msg) \
735 do { \
736 if (_LOG_DEBUG_ENABLED) { \
737 ws_log_buffer_full(_LOG_DOMAIN, LOG_LEVEL_DEBUG, \
738 __FILE__, __LINE__, __func__, \
739 buf, size, 36, msg ? msg : #buf); \
740 } \
741 } while (0)
742
743
759WS_DLL_PUBLIC
760void ws_log_write_always_full(const char *domain, enum ws_log_level level,
761 const char *file, long line, const char *func,
762 const char *format, ...) G_GNUC_PRINTF(6,7);
763
764
773WS_DLL_PUBLIC
774void ws_log_add_custom_file(FILE *fp);
775
776
785WS_DLL_PUBLIC
786void ws_log_print_usage(FILE *fp);
787
788#ifdef __cplusplus
789}
790#endif /* __cplusplus */
791
792#endif /* __WSLOG_H__ */
Definition mcast_stream.h:30
Log manifest entry containing timestamp and process ID.
Definition wslog.h:77
intmax_t pid
Definition wslog.h:80
long nanosecs
Definition wslog.h:79
Structure representing a long-form command-line option.
Definition ws_getopt.h:64
WS_DLL_PUBLIC void ws_log(const char *domain, enum ws_log_level level, const char *format,...) G_GNUC_PRINTF(3
Output a formatted message to the log.
WS_DLL_PUBLIC void ws_log_set_writer_with_data(ws_log_writer_cb *writer, void *user_data, ws_log_writer_free_data_cb *free_user_data)
Set the active log writer with user data.
Definition wslog.c:623
WS_DLL_PUBLIC void ws_log_set_domain_filter(const char *domain_filter)
Set a domain filter from a string.
Definition wslog.c:561
WS_DLL_PUBLIC void ws_log_console_writer(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, ws_log_manifest_t *mft, const char *user_format, va_list user_ap)
Write a formatted log message to the console.
Definition wslog.c:1202
WS_DLL_PUBLIC void ws_log_set_debug_filter(const char *str_filter)
Set a debug filter from a string.
Definition wslog.c:575
WS_DLL_PUBLIC void ws_log_print_usage(FILE *fp)
Print usage information for logging-related command-line options.
Definition wslog.c:1268
void() ws_log_writer_free_data_cb(void *user_data)
Definition wslog.h:92
WS_DLL_PUBLIC void ws_log_file_writer(FILE *fp, const char *domain, enum ws_log_level level, const char *file, long line, const char *func, ws_log_manifest_t *mft, const char *user_format, va_list user_ap)
Write a formatted log message to a file stream.
Definition wslog.c:1190
ws_log_console_open_pref
Console open preference for logging output.
Definition wslog.h:61
@ LOG_CONSOLE_OPEN_ALWAYS
Definition wslog.h:64
@ LOG_CONSOLE_OPEN_NEVER
Definition wslog.h:62
@ LOG_CONSOLE_OPEN_AUTO
Definition wslog.h:63
WS_DLL_PUBLIC void ws_log_set_fatal_domain_filter(const char *domain_filter)
Set a fatal domain filter from a string.
Definition wslog.c:568
WS_DLL_PUBLIC void ws_log_console_writer_set_use_stdout(bool use_stdout)
Configure log levels "info" and below to use stdout.
Definition wslog.c:1215
WS_DLL_PUBLIC enum ws_log_level ws_log_set_level(enum ws_log_level level)
Set the active log level.
Definition wslog.c:351
WS_DLL_PUBLIC WS_NORETURN void ws_log_fatal_full(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, const char *format,...) G_GNUC_PRINTF(6
Output a fatal log message with source context and abort the program.
WS_DLL_PUBLIC void ws_log_set_noisy_filter(const char *str_filter)
Set a noisy filter from a string.
Definition wslog.c:582
WS_DLL_PUBLIC void WS_DLL_PUBLIC void ws_logv_full(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, const char *format, va_list ap)
Output a formatted log message with source context using a va_list.
Definition wslog.c:996
WS_DLL_PUBLIC int ws_log_parse_args(int *argc_ptr, char *argv[], const char *optstring, const struct ws_option *long_options, void(*vcmdarg_err)(const char *, va_list ap), int exit_failure)
Parse command-line arguments for log options.
Definition wslog.c:388
WS_DLL_PUBLIC void ws_log_write_always_full(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, const char *format,...) G_GNUC_PRINTF(6
Emit a log message unconditionally with full source context.
void() ws_log_writer_cb(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, const char *fatal_msg, ws_log_manifest_t *mft, const char *user_format, va_list user_ap, void *user_data)
Definition wslog.h:84
WS_DLL_PUBLIC void ws_log_buffer_full(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, const uint8_t *buffer, size_t size, size_t max_bytes_len, const char *msg)
Output a formatted log message for a byte buffer with source context.
Definition wslog.c:1168
WS_DLL_PUBLIC enum ws_log_level ws_log_set_fatal_level(enum ws_log_level level)
Set the fatal log level.
Definition wslog.c:589
WS_DLL_PUBLIC void ws_log_init(void(*vcmdarg_err)(const char *, va_list ap))
Initialize the logging system.
Definition wslog.c:695
WS_DLL_PUBLIC void WS_DLL_PUBLIC void ws_log_add_custom_file(FILE *fp)
Add an auxiliary file output for log messages.
Definition wslog.c:1238
WS_DLL_PUBLIC WS_RETNONNULL const char * ws_log_level_to_string(enum ws_log_level level)
Convert a numerical log level to its string representation.
Definition wslog.c:137
WS_DLL_PUBLIC void ws_log_full(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, const char *format,...) G_GNUC_PRINTF(6
Output a formatted log message with source context.
WS_DLL_PUBLIC void ws_log_init_with_writer(ws_log_writer_cb *writer, void(*vcmdarg_err)(const char *, va_list ap))
Initialize the logging system with a custom writer.
Definition wslog.c:771
WS_DLL_PUBLIC void WS_DLL_PUBLIC void ws_logv(const char *domain, enum ws_log_level level, const char *format, va_list ap)
Output a formatted message to the log using a va_list.
Definition wslog.c:985
WS_DLL_PUBLIC void ws_log_init_with_writer_and_data(ws_log_writer_cb *writer, void *user_data, ws_log_writer_free_data_cb *free_user_data, void(*vcmdarg_err)(const char *, va_list ap))
Initialize the logging system with a custom writer and user data.
Definition wslog.c:779
WS_DLL_PUBLIC bool ws_log_is_wslog_arg(int arg)
Determine if a command-line argument is used by wslog.
Definition wslog.c:503
WS_DLL_PUBLIC void ws_log_utf8_full(const char *domain, enum ws_log_level level, const char *file, long line, const char *func, const char *string, ssize_t length, const char *endptr)
Output a UTF-8 encoded log message with source context.
Definition wslog.c:1133
WS_DLL_PUBLIC enum ws_log_level ws_log_get_level(void)
Get the currently active global log level.
Definition wslog.c:345
WS_DLL_PUBLIC void ws_log_set_writer(ws_log_writer_cb *writer)
Set the active log writer.
Definition wslog.c:612
WS_DLL_PUBLIC bool ws_log_msg_is_active(const char *domain, enum ws_log_level level)
Check if a log message will be output for a given domain and level.
Definition wslog.c:279
WS_DLL_PUBLIC enum ws_log_level ws_log_set_fatal_level_str(const char *str_level)
Set the fatal log level from a string.
Definition wslog.c:603
WS_DLL_PUBLIC enum ws_log_level ws_log_set_level_str(const char *str_level)
Set the active log level from a string.
Definition wslog.c:363