wsutil/wslog.h

   1 /** @file
   2  *
   3  * Copyright 2021, João Valverde <j@v6e.pt>
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  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
  27 #ifdef WS_LOG_DOMAIN
  28 #define _LOG_DOMAIN WS_LOG_DOMAIN
  29 #else
  30 #define _LOG_DOMAIN ""
  31 #endif
  32
  33 #ifdef WS_DEBUG
  34 #define _LOG_DEBUG_ENABLED true
  35 #else
  36 #define _LOG_DEBUG_ENABLED false
  37 #endif
  38
  39 /*
  40  * Define the macro WS_LOG_DOMAIN *before* including this header,
  41  * for example:
  42  *   #define WS_LOG_DOMAIN LOG_DOMAIN_MAIN
  43  */
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif /* __cplusplus */
  48
  49 /*
  50  * Console open preference is stored in the Windows registry.
  51  *   HKEY_CURRENT_USER\Software\Wireshark\ConsoleOpen
  52  */
  53 #define LOG_HKCU_CONSOLE_OPEN   "ConsoleOpen"
  54
  55 typedef enum {
  56     LOG_CONSOLE_OPEN_NEVER,
  57     LOG_CONSOLE_OPEN_AUTO, /* On demand. */
  58     LOG_CONSOLE_OPEN_ALWAYS, /* Open during startup. */
  59 } ws_log_console_open_pref;
  60
  61 WSUTIL_EXPORT
  62 ws_log_console_open_pref ws_log_console_open;
  63
  64 typedef struct {
  65     struct tm tstamp_secs;
  66     long nanosecs;
  67     intmax_t pid;
  68 } ws_log_manifest_t;
  69
  70 /** Callback for registering a log writer. */
  71 typedef void (ws_log_writer_cb)(const char *domain, enum ws_log_level level,
  72                             const char *file, long line, const char *func,
  73                             const char *fatal_msg, ws_log_manifest_t *mft,
  74                             const char *user_format, va_list user_ap,
  75                             void *user_data);
  76
  77
  78 /** Callback for freeing a user data pointer. */
  79 typedef void (ws_log_writer_free_data_cb)(void *user_data);
  80
  81
  82 WS_DLL_PUBLIC
  83 void ws_log_file_writer(FILE *fp, const char *domain, enum ws_log_level level,
  84                             const char *file, long line, const char *func,
  85                             ws_log_manifest_t *mft,
  86                             const char *user_format, va_list user_ap);
  87
  88
  89 WS_DLL_PUBLIC
  90 void ws_log_console_writer(const char *domain, enum ws_log_level level,
  91                             const char *file, long line, const char *func,
  92                             ws_log_manifest_t *mft,
  93                             const char *user_format, va_list user_ap);
  94
  95
  96 /** Configure log levels "info" and below to use stdout.
  97  *
  98  * Normally all log messages are written to stderr. For backward compatibility
  99  * with GLib calling this function with true configures log levels "info",
 100  * "debug" and "noisy" to be written to stdout.
 101  */
 102 WS_DLL_PUBLIC
 103 void ws_log_console_writer_set_use_stdout(bool use_stdout);
 104
 105
 106 /** Convert a numerical level to its string representation. */
 107 WS_DLL_PUBLIC
 108 WS_RETNONNULL
 109 const char *ws_log_level_to_string(enum ws_log_level level);
 110
 111
 112 /** Checks if a domain and level combination generate output.
 113  *
 114  * Returns true if a message will be printed for the domain/level combo.
 115  */
 116 WS_DLL_PUBLIC
 117 bool ws_log_msg_is_active(const char *domain, enum ws_log_level level);
 118
 119
 120 /** Return the currently active log level. */
 121 WS_DLL_PUBLIC
 122 enum ws_log_level ws_log_get_level(void);
 123
 124
 125 /** Set the active log level. Returns the active level or LOG_LEVEL_NONE
 126  * if level is invalid. */
 127 WS_DLL_PUBLIC
 128 enum ws_log_level ws_log_set_level(enum ws_log_level level);
 129
 130
 131 /** Set the active log level from a string.
 132  *
 133  * String levels are "error", "critical", "warning", "message", "info",
 134  * "debug" and "noisy" (case insensitive).
 135  * Returns the new log level or LOG_LEVEL NONE if the string representation
 136  * is invalid.
 137  */
 138 WS_DLL_PUBLIC
 139 enum ws_log_level ws_log_set_level_str(const char *str_level);
 140
 141
 142 /** Set a domain filter from a string.
 143  *
 144  * Domain filter is a case insensitive list separated by ',' or ';'. Only
 145  * the domains in the filter will generate output; the others will be muted.
 146  * Filter expressions can be preceded by '!' to invert the sense of the match.
 147  * In this case only non-matching domains will generate output.
 148  */
 149 WS_DLL_PUBLIC
 150 void ws_log_set_domain_filter(const char *domain_filter);
 151
 152 /** Set a fatal domain filter from a string.
 153  *
 154  * Domain filter is a case insensitive list separated by ',' or ';'. Domains
 155  * in the filter will cause the program to abort.
 156  */
 157 WS_DLL_PUBLIC
 158 void ws_log_set_fatal_domain_filter(const char *domain_filter);
 159
 160
 161 /** Set a debug filter from a string.
 162  *
 163  * A debug filter lists all domains that should have debug level output turned
 164  * on, regardless of the global log level and domain filter. If negated
 165  * then debug (and below) will be disabled and the others unaffected by
 166  * the filter.
 167  */
 168 WS_DLL_PUBLIC
 169 void ws_log_set_debug_filter(const char *str_filter);
 170
 171
 172 /** Set a noisy filter from a string.
 173  *
 174  * Same as ws_log_set_debug_filter() for "noisy" level.
 175  */
 176 WS_DLL_PUBLIC
 177 void ws_log_set_noisy_filter(const char *str_filter);
 178
 179
 180 /** Set the fatal log level.
 181  *
 182  * Sets the log level at which calls to ws_log() will abort the program. The
 183  * argument can be LOG_LEVEL_ERROR, LOG_LEVEL_CRITICAL or LOG_LEVEL_WARNING.
 184  * Level LOG_LEVEL_ERROR is always fatal.
 185  */
 186 WS_DLL_PUBLIC
 187 enum ws_log_level ws_log_set_fatal_level(enum ws_log_level level);
 188
 189
 190 /** Set the fatal log level from a string.
 191  *
 192  * Same as ws_log_set_fatal(), but accepts the strings "error", critical" or
 193  * "warning" instead as arguments.
 194  */
 195 WS_DLL_PUBLIC
 196 enum ws_log_level  ws_log_set_fatal_level_str(const char *str_level);
 197
 198
 199 /** Set the active log writer.
 200  *
 201  * The parameter 'writer' can be NULL to use the default writer.
 202  */
 203 WS_DLL_PUBLIC
 204 void ws_log_set_writer(ws_log_writer_cb *writer);
 205
 206
 207 /** Set the active log writer.
 208  *
 209  * The parameter 'writer' can be NULL to use the default writer.
 210  * Accepts an extra user_data parameter that will be passed to
 211  * the log writer.
 212  */
 213 WS_DLL_PUBLIC
 214 void ws_log_set_writer_with_data(ws_log_writer_cb *writer,
 215                         void *user_data,
 216                         ws_log_writer_free_data_cb *free_user_data);
 217
 218
 219 #define LOG_ARGS_NOEXIT -1
 220
 221 /** Parses the command line arguments for log options.
 222  *
 223  * Returns zero for no error, non-zero for one or more invalid options.
 224  */
 225 WS_DLL_PUBLIC
 226 int ws_log_parse_args(int *argc_ptr, char *argv[],
 227                         void (*vcmdarg_err)(const char *, va_list ap),
 228                         int exit_failure);
 229
 230
 231 /** Initializes the logging code.
 232  *
 233  * Must be called at startup before using the log API. If provided
 234  * vcmdarg_err is used to print initialization errors. This usually means
 235  * a misconfigured environment variable.
 236  */
 237 WS_DLL_PUBLIC
 238 void ws_log_init(void (*vcmdarg_err)(const char *, va_list ap));
 239
 240
 241 /** Initializes the logging code.
 242  *
 243  * Can be used instead of wslog_init(). Takes an extra writer argument.
 244  * If provided this callback will be used instead of the default writer.
 245  */
 246 WS_DLL_PUBLIC
 247 void ws_log_init_with_writer(ws_log_writer_cb *writer,
 248                         void (*vcmdarg_err)(const char *, va_list ap));
 249
 250
 251 /** Initializes the logging code.
 252  *
 253  * Accepts a user data pointer in addition to the writer. This pointer will
 254  * be provided to the writer with every invocation. If provided
 255  * free_user_data will be called during cleanup.
 256  */
 257 WS_DLL_PUBLIC
 258 void ws_log_init_with_writer_and_data(ws_log_writer_cb *writer,
 259                         void *user_data,
 260                         ws_log_writer_free_data_cb *free_user_data,
 261                         void (*vcmdarg_err)(const char *, va_list ap));
 262
 263
 264 /** This function is called to output a message to the log.
 265  *
 266  * Takes a format string and a variable number of arguments.
 267  */
 268 WS_DLL_PUBLIC
 269 void ws_log(const char *domain, enum ws_log_level level,
 270                     const char *format, ...) G_GNUC_PRINTF(3,4);
 271
 272
 273 /** This function is called to output a message to the log.
 274  *
 275  * Takes a format string and a 'va_list'.
 276  */
 277 WS_DLL_PUBLIC
 278 void ws_logv(const char *domain, enum ws_log_level level,
 279                     const char *format, va_list ap);
 280
 281
 282 /** This function is called to output a message to the log.
 283  *
 284  * In addition to the message this function accepts file/line/function
 285  * information.
 286  */
 287 WS_DLL_PUBLIC
 288 void ws_log_full(const char *domain, enum ws_log_level level,
 289                     const char *file, long line, const char *func,
 290                     const char *format, ...) G_GNUC_PRINTF(6,7);
 291
 292
 293 /** This function is called to output a message to the log.
 294  *
 295  * In addition to the message this function accepts file/line/function
 296  * information.
 297  */
 298 WS_DLL_PUBLIC
 299 void ws_logv_full(const char *domain, enum ws_log_level level,
 300                     const char *file, long line, const char *func,
 301                     const char *format, va_list ap);
 302
 303
 304 WS_DLL_PUBLIC
 305 WS_NORETURN
 306 void ws_log_fatal_full(const char *domain, enum ws_log_level level,
 307                     const char *file, long line, const char *func,
 308                     const char *format, ...) G_GNUC_PRINTF(6,7);
 309
 310
 311 /*
 312  * The if condition avoids -Wunused warnings for variables used only with
 313  * WS_DEBUG, typically inside a ws_debug() call. The compiler will
 314  * optimize away the dead execution branch.
 315  */
 316 #define _LOG_IF_ACTIVE(active, level, file, line, func, ...) \
 317         do {                                        \
 318             if (active) {                           \
 319                 ws_log_full(_LOG_DOMAIN, level,     \
 320                             file, line, func,       \
 321                             __VA_ARGS__);           \
 322             }                                       \
 323         } while (0)
 324
 325 #define _LOG_FULL(active, level, ...) \
 326         _LOG_IF_ACTIVE(active, level, __FILE__, __LINE__, __func__, __VA_ARGS__)
 327
 328 #define _LOG_SIMPLE(active, level, ...) \
 329         _LOG_IF_ACTIVE(active, level, NULL, -1, NULL, __VA_ARGS__)
 330
 331 /** Logs with "error" level.
 332  *
 333  * Accepts a format string and includes the file and function name.
 334  *
 335  * "error" is always fatal and terminates the program with a coredump.
 336  */
 337 #define ws_error(...) \
 338         ws_log_fatal_full(_LOG_DOMAIN, LOG_LEVEL_ERROR, \
 339                             __FILE__, __LINE__, __func__, __VA_ARGS__)
 340
 341 /** Logs with "critical" level.
 342  *
 343  * Accepts a format string and includes the file and function name.
 344  */
 345 #define ws_critical(...) \
 346         _LOG_FULL(true, LOG_LEVEL_CRITICAL, __VA_ARGS__)
 347
 348 /** Logs with "warning" level.
 349  *
 350  * Accepts a format string and includes the file and function name.
 351  */
 352 #define ws_warning(...) \
 353         _LOG_FULL(true, LOG_LEVEL_WARNING, __VA_ARGS__)
 354
 355 /** Logs with "message" level.
 356  *
 357  * Accepts a format string and does not include the file and function
 358  * name (use ws_log_full instead). This is the default log level.
 359  */
 360 #define ws_message(...) \
 361         _LOG_SIMPLE(true, LOG_LEVEL_MESSAGE, __VA_ARGS__)
 362
 363 /** Logs with "info" level.
 364  *
 365  * Accepts a format string and does not include the file and function
 366  * name (use ws_log_full instead).
 367  */
 368 #define ws_info(...) \
 369         _LOG_SIMPLE(true, LOG_LEVEL_INFO, __VA_ARGS__)
 370
 371 /** Logs with "debug" level.
 372  *
 373  * Accepts a format string and includes the file and function name.
 374  */
 375 #define ws_debug(...) \
 376         _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_DEBUG, __VA_ARGS__)
 377
 378 /** Logs with "noisy" level.
 379  *
 380  * Accepts a format string and includes the file and function name.
 381  */
 382 #define ws_noisy(...) \
 383         _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_NOISY, __VA_ARGS__)
 384
 385 /** Used for temporary debug print outs, always active. */
 386 #define WS_DEBUG_HERE(...) \
 387         _LOG_FULL(true, LOG_LEVEL_ECHO, __VA_ARGS__)
 388
 389 #define WS_NOT_IMPLEMENTED() \
 390         ws_error("Not implemented yet")
 391
 392 WS_DLL_PUBLIC
 393 void ws_log_utf8_full(const char *domain, enum ws_log_level level,
 394                     const char *file, long line, const char *func,
 395                     const char *string, ssize_t length, const char *endptr);
 396
 397
 398 #define ws_log_utf8(str, len, endptr) \
 399     do {                                                        \
 400         if (_LOG_DEBUG_ENABLED) {                               \
 401             ws_log_utf8_full(LOG_DOMAIN_UTF_8, LOG_LEVEL_DEBUG, \
 402                                 __FILE__, __LINE__, __func__,   \
 403                                 str, len, endptr);              \
 404         }                                                       \
 405     } while (0)
 406
 407
 408 /** This function is called to log a buffer (bytes array).
 409  *
 410  * Accepts an optional 'msg' argument to provide a description.
 411  */
 412 WS_DLL_PUBLIC
 413 void ws_log_buffer_full(const char *domain, enum ws_log_level level,
 414                     const char *file, long line, const char *func,
 415                     const uint8_t *buffer, size_t size,
 416                     size_t max_bytes_len, const char *msg);
 417
 418
 419 #define ws_log_buffer(buf, size, msg) \
 420         do {                                                        \
 421             if (_LOG_DEBUG_ENABLED) {                               \
 422                 ws_log_buffer_full(_LOG_DOMAIN, LOG_LEVEL_DEBUG,    \
 423                         __FILE__, __LINE__, __func__,               \
 424                         buf, size, 36, msg ? msg : #buf);           \
 425             }                                                       \
 426         } while (0)
 427
 428
 429 /** Auxiliary function to write custom logging functions.
 430  *
 431  * This function is the same as ws_log_full() but does not perform any
 432  * domain/level filtering to avoid a useless double activation check.
 433  * It should only be used in conjunction with a pre-check using
 434  * ws_log_msg_is_active().
 435  */
 436 WS_DLL_PUBLIC
 437 void ws_log_write_always_full(const char *domain, enum ws_log_level level,
 438                     const char *file, long line, const char *func,
 439                     const char *format, ...) G_GNUC_PRINTF(6,7);
 440
 441
 442 /** Define an auxiliary file pointer where messages should be written.
 443  *
 444  * This file, if set, functions in addition to the registered or
 445  * default log writer.
 446  */
 447 WS_DLL_PUBLIC
 448 void ws_log_add_custom_file(FILE *fp);
 449
 450
 451 WS_DLL_PUBLIC
 452 void ws_log_print_usage(FILE *fp);
 453
 454 #ifdef __cplusplus
 455 }
 456 #endif /* __cplusplus */
 457
 458 #endif /* __WSLOG_H__ */