| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions | Variables
wslog.h File Reference
`#include <inttypes.h>`
`#include <stdbool.h>`
`#include <stdio.h>`
`#include <stdarg.h>`
`#include <time.h>`
`#include <glib.h>`
`#include <ws_symbol_export.h>`
`#include <ws_attributes.h>`
`#include <ws_log_defs.h>`
`#include <ws_posix_compat.h>`
`#include "ws_getopt.h"`

Go to the source code of this file.

## Classes
struct | ws_log_manifest_t
| Log manifest entry containing timestamp and process ID. More...

## Macros
#define | _LOG_DOMAIN ""
#define | _LOG_DEBUG_ENABLED false
#define | LOG_HKCU_CONSOLE_OPEN "ConsoleOpen"
#define | LOG_ARGS_NOEXIT -1
#define | LONGOPT_WSLOG_LOG_LEVEL LONGOPT_BASE_WSLOG+1
#define | LONGOPT_WSLOG_LOG_DOMAIN LONGOPT_BASE_WSLOG+2
#define | LONGOPT_WSLOG_LOG_FILE LONGOPT_BASE_WSLOG+3
#define | LONGOPT_WSLOG_LOG_FATAL LONGOPT_BASE_WSLOG+4
#define | LONGOPT_WSLOG_LOG_FATAL_DOMAIN LONGOPT_BASE_WSLOG+5
#define | LONGOPT_WSLOG_LOG_DEBUG LONGOPT_BASE_WSLOG+6
#define | LONGOPT_WSLOG_LOG_NOISY LONGOPT_BASE_WSLOG+7
#define | LONGOPT_WSLOG
#define | _LOG_IF_ACTIVE(active, level, file, line, func, ...)
#define | _LOG_FULL(active, level, ...) _LOG_IF_ACTIVE(active, level, __FILE__, __LINE__, __func__, __VA_ARGS__)
#define | _LOG_SIMPLE(active, level, ...) _LOG_IF_ACTIVE(active, level, NULL, -1, NULL, __VA_ARGS__)
#define | ws_error(...)
| Log a fatal "error" level message and terminate the program.
#define | ws_critical(...) _LOG_FULL(true, LOG_LEVEL_CRITICAL, __VA_ARGS__)
| Log a "critical" level message with source context.
#define | ws_warning(...) _LOG_FULL(true, LOG_LEVEL_WARNING, __VA_ARGS__)
| Log a "warning" level message with source context.
#define | ws_message(...) _LOG_SIMPLE(true, LOG_LEVEL_MESSAGE, __VA_ARGS__)
| Log a "message" level entry without source context.
#define | ws_info(...) _LOG_SIMPLE(true, LOG_LEVEL_INFO, __VA_ARGS__)
| Log an "info" level entry without source context.
#define | ws_debug(...) _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_DEBUG, __VA_ARGS__)
| Log a "debug" level message with source context.
#define | ws_noisy(...) _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_NOISY, __VA_ARGS__)
| Log a "noisy" level message with source context.
#define | WS_DEBUG_HERE(...) _LOG_FULL(true, LOG_LEVEL_ECHO, __VA_ARGS__)
| Emit a temporary debug message with source context.
#define | WS_NOT_IMPLEMENTED() ws_error("Not implemented yet")
| Log a fatal error indicating unimplemented functionality.
#define | ws_log_utf8(str, len, endptr)
| Emit a UTF-8 debug log message with source context.
#define | ws_log_buffer(buf, size, msg)
| Log a byte buffer at debug level with source context.

## Typedefs
typedef 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)
typedef void() | ws_log_writer_free_data_cb(void *user_data)

## Enumerations
enum | ws_log_console_open_pref { LOG_CONSOLE_OPEN_NEVER , LOG_CONSOLE_OPEN_AUTO , LOG_CONSOLE_OPEN_ALWAYS }
| Console open preference for logging output. More...

## Functions
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.
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.
WS_DLL_PUBLIC void | ws_log_console_writer_set_use_stdout (bool use_stdout)
| Configure log levels "info" and below to use stdout.
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.
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.
WS_DLL_PUBLIC enum ws_log_level | ws_log_get_level (void)
| Get the currently active global log level.
WS_DLL_PUBLIC enum ws_log_level | ws_log_set_level (enum ws_log_level level)
| Set the active log level.
WS_DLL_PUBLIC enum ws_log_level | ws_log_set_level_str (const char *str_level)
| Set the active log level from a string.
WS_DLL_PUBLIC void | ws_log_set_domain_filter (const char *domain_filter)
| Set a domain filter from a string.
WS_DLL_PUBLIC void | ws_log_set_fatal_domain_filter (const char *domain_filter)
| Set a fatal domain filter from a string.
WS_DLL_PUBLIC void | ws_log_set_debug_filter (const char *str_filter)
| Set a debug filter from a string.
WS_DLL_PUBLIC void | ws_log_set_noisy_filter (const char *str_filter)
| Set a noisy filter from a string.
WS_DLL_PUBLIC enum ws_log_level | ws_log_set_fatal_level (enum ws_log_level level)
| Set the fatal log level.
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.
WS_DLL_PUBLIC void | ws_log_set_writer (ws_log_writer_cb *writer)
| Set the active log writer.
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.
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.
WS_DLL_PUBLIC bool | ws_log_is_wslog_arg (int arg)
| Determine if a command-line argument is used by wslog.
WS_DLL_PUBLIC void | ws_log_init (void(*vcmdarg_err)(const char *, va_list ap), const char *console_title)
| Initialize the logging system.
WS_DLL_PUBLIC void | ws_log_init_with_writer (ws_log_writer_cb *writer, void(*vcmdarg_err)(const char *, va_list ap), const char *console_title)
| Initialize the logging system with a custom writer.
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), const char *console_title)
| Initialize the logging system with a custom writer and user data.
WS_DLL_PUBLIC void | ws_log (const char *domain, enum ws_log_level level, const char *format,...)
| Output a formatted message to the log.
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.
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,...)
| Output a formatted log message with source context.
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.
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,...)
| Output a fatal log message with source context and abort the program.
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.
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.
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,...)
| Emit a log message unconditionally with full source context.
WS_DLL_PUBLIC void | ws_log_add_custom_file (FILE *fp)
| Add an auxiliary file output for log messages.
WS_DLL_PUBLIC void | ws_log_print_usage (FILE *fp)
| Print usage information for logging-related command-line options.

## Variables
WSUTIL_EXPORT ws_log_console_open_pref | ws_log_console_open

## Detailed Description

Copyright 2021, João Valverde j@v6e.nosp@m..pt

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

## Macro Definition Documentation

## ◆ _LOG_IF_ACTIVE

#define _LOG_IF_ACTIVE | ( |  | active,
|  |  | level,
|  |  | file,
|  |  | line,
|  |  | func,
|  |  | ...
| ) |  |

Value:
do { \
if (active) { \
ws_log_full(_LOG_DOMAIN, level, \
file, line, func, \
__VA_ARGS__); \
} \
} while (0)

## ◆ LONGOPT_WSLOG

#define LONGOPT_WSLOG

Value:
{"log-level", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_LEVEL}, \
{"log-domain", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_DOMAIN}, \
/* Alias "domain" and "domains". */ \
{"log-domains", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_DOMAIN}, \
{"log-file", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FILE}, \
{"log-fatal", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FATAL}, \
/* Alias "domain" and "domains". */ \
{"log-fatal-domain", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FATAL_DOMAIN}, \
{"log-fatal-domains", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_FATAL_DOMAIN}, \
{"log-debug", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_DEBUG}, \
{"log-noisy", ws_required_argument, NULL, LONGOPT_WSLOG_LOG_NOISY},

Logging options for command line

## ◆ ws_critical

#define ws_critical | ( |  | ... | ) | _LOG_FULL(true, LOG_LEVEL_CRITICAL, __VA_ARGS__)

Log a "critical" level message with source context.

Emits a log message with "critical" severity, including file name, line number, and function name. Used for serious issues that do not terminate the program.

Parameters

  ... | printf-style format string and arguments for the log message.

## ◆ ws_debug

#define ws_debug | ( |  | ... | ) | _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_DEBUG, __VA_ARGS__)

Log a "debug" level message with source context.

Emits a log message with "debug" severity, including file name, line number, and function name. Logging occurs only if debugging is enabled via _LOG_DEBUG_ENABLED.

Parameters

  ... | printf-style format string and arguments for the log message.

## ◆ WS_DEBUG_HERE

#define WS_DEBUG_HERE | ( |  | ... | ) | _LOG_FULL(true, LOG_LEVEL_ECHO, __VA_ARGS__)

Emit a temporary debug message with source context.

Used for ad-hoc or temporary debug printouts. Always active regardless of log level settings. Includes file name, line number, and function name.

Parameters

  ... | printf-style format string and arguments for the log message.

## ◆ ws_error

#define ws_error | ( |  | ... | ) |

Value:
ws_log_fatal_full(_LOG_DOMAIN, LOG_LEVEL_ERROR, \
__FILE__, __LINE__, __func__, __VA_ARGS__)
ws_log_fatal_full
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,...)
Output a fatal log message with source context and abort the program.
Definition wslog.c:1043

Log a fatal "error" level message and terminate the program.

Emits a log message with "error" severity, including file name, line number, and function name. This macro always results in program termination with a coredump.

Parameters

  ... | printf-style format string and arguments for the log message.

## ◆ ws_info

#define ws_info | ( |  | ... | ) | _LOG_SIMPLE(true, LOG_LEVEL_INFO, __VA_ARGS__)

Log an "info" level entry without source context.

Emits a log message with "info" severity, typically used for general informational output. Does not include file name, line number, or function name. For full context, use ws_log_full instead.

Parameters

  ... | printf-style format string and arguments for the log message.

## ◆ ws_log_buffer

#define ws_log_buffer | ( |  | buf,
|  |  | size,
|  |  | msg
| ) |  |

Value:
do { \
if (_LOG_DEBUG_ENABLED) { \
ws_log_buffer_full(_LOG_DOMAIN, LOG_LEVEL_DEBUG, \
__FILE__, __LINE__, __func__, \
buf, size, 36, msg ? msg : #buf); \
} \
} while (0)

Log a byte buffer at debug level with source context.

Emits a debug-level log message for a byte buffer, including file name, line number, and function name. Displays up to 36 bytes. If no message is provided, the buffer variable name is used as a fallback.

Parameters

  buf | Pointer to the byte buffer.
  size | Size of the buffer in bytes.
  msg | Optional description of the buffer.

## ◆ ws_log_utf8

#define ws_log_utf8 | ( |  | str,
|  |  | len,
|  |  | endptr
| ) |  |

Value:
do { \
if (_LOG_DEBUG_ENABLED) { \
ws_log_utf8_full(LOG_DOMAIN_UTF_8, LOG_LEVEL_DEBUG, \
__FILE__, __LINE__, __func__, \
str, len, endptr); \
} \
} while (0)

Emit a UTF-8 debug log message with source context.

Logs a UTF-8 encoded string at "debug" level, including file name, line number, and function name. Logging occurs only if debugging is enabled via _LOG_DEBUG_ENABLED.

Parameters

  str | UTF-8 encoded message string.
  len | Length of the message string in bytes.
  endptr | Optional pointer to the end of the message range.

## ◆ ws_message

#define ws_message | ( |  | ... | ) | _LOG_SIMPLE(true, LOG_LEVEL_MESSAGE, __VA_ARGS__)

Log a "message" level entry without source context.

Emits a log message with "message" severity, the default log level. Does not include file name, line number, or function name. For full context, use ws_log_full instead.

Parameters

  ... | printf-style format string and arguments for the log message.

## ◆ ws_noisy

#define ws_noisy | ( |  | ... | ) | _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_NOISY, __VA_ARGS__)

Log a "noisy" level message with source context.

Emits a log message with "noisy" severity, typically used for verbose or low-level diagnostic output. Includes file name, line number, and function name. Logging occurs only if debugging is enabled via _LOG_DEBUG_ENABLED.

Parameters

  ... | printf-style format string and arguments for the log message.

## ◆ WS_NOT_IMPLEMENTED

#define WS_NOT_IMPLEMENTED | ( |  | ) | ws_error("Not implemented yet")

Log a fatal error indicating unimplemented functionality.

Emits an "error" level message and terminates the program with a coredump. Used as a placeholder for unimplemented code paths.

## ◆ ws_warning

#define ws_warning | ( |  | ... | ) | _LOG_FULL(true, LOG_LEVEL_WARNING, __VA_ARGS__)

Log a "warning" level message with source context.

Emits a log message with "warning" severity, including file name, line number, and function name. Used to report recoverable issues or unexpected conditions.

Parameters

  ... | printf-style format string and arguments for the log message.

## Typedef Documentation

## ◆ ws_log_writer_cb

typedef 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)

Callback for registering a log writer.

## ◆ ws_log_writer_free_data_cb

typedef void() ws_log_writer_free_data_cb(void *user_data)

Callback for freeing a user data pointer.

## Enumeration Type Documentation

## ◆ ws_log_console_open_pref

enum ws_log_console_open_pref

Console open preference for logging output.

Specifies when the console window should be opened for log messages.

Enumerator
LOG_CONSOLE_OPEN_NEVER | Never open the console.
LOG_CONSOLE_OPEN_AUTO | Open on demand.
LOG_CONSOLE_OPEN_ALWAYS | Open during startup.

## Function Documentation

## ◆ ws_log()

WS_DLL_PUBLIC void ws_log | ( | const char * | domain,
|  | enum ws_log_level | level,
|  | const char * | format,
|  |  | ...
| ) |  |

Output a formatted message to the log.

This function emits a log message for the specified domain and level. The message is constructed using a printf-style format string and a variable number of arguments.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  format | printf-style format string for the log message.
  ... | Variable arguments matching the format string.

## ◆ ws_log_add_custom_file()

WS_DLL_PUBLIC void ws_log_add_custom_file | ( | FILE * | fp | ) |

Add an auxiliary file output for log messages.

Defines an additional file pointer where log messages should be written. This output is used in addition to the registered or default log writer.

Parameters

  fp | File pointer to write log messages to.

## ◆ ws_log_buffer_full()

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.

Logs a buffer (byte array) at the specified domain and level, including source file name, line number, and function name. An optional message can be provided to describe the buffer contents.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  buffer | Pointer to the byte buffer to log.
  size | Size of the buffer in bytes.
  max_bytes_len | Maximum number of bytes to display in the log.
  msg | Optional description of the buffer.

## ◆ ws_log_console_writer()

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.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  mft | Pointer to log manifest metadata (timestamp, PID).
  user_format | User-supplied format string (printf-style).
  user_ap | Variable argument list for the format string.

## ◆ ws_log_console_writer_set_use_stdout()

WS_DLL_PUBLIC void ws_log_console_writer_set_use_stdout | ( | bool | use_stdout | ) |

Configure log levels "info" and below to use stdout.

Normally, all log messages are written to stderr. For backward compatibility with GLib, calling this function with true configures log levels "info", "debug", and "noisy" to be written to stdout.

Parameters

  use_stdout | If true, log levels "info" and below will be written to stdout. Otherwise, all logs go to stderr.

## ◆ ws_log_fatal_full()

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,
|  |  | ...
| ) |  |

Output a fatal log message with source context and abort the program.

Emits a log message for the specified domain and level, including source file name, line number, and function name. This function does not return; it terminates the program after logging the message.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  format | printf-style format string for the log message.
  ... | Variable arguments matching the format string.

## ◆ ws_log_file_writer()

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.

Parameters

  fp | Output file stream to write the log message.
  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  mft | Pointer to log manifest metadata (timestamp, PID).
  user_format | User-supplied format string (printf-style).
  user_ap | Variable argument list for the format string.

## ◆ ws_log_full()

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,
|  |  | ...
| ) |  |

Output a formatted log message with source context.

This function emits a log message for the specified domain and level, including source file name, line number, and function name for context. The message is constructed using a printf-style format string and a variable number of arguments.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  format | printf-style format string for the log message.
  ... | Variable arguments matching the format string.

## ◆ ws_log_get_level()

WS_DLL_PUBLIC enum ws_log_level ws_log_get_level | ( | void |  | ) |

Get the currently active global log level.

This level determines the minimum severity of messages that will be logged.

Returns
  Current global log level.

## ◆ ws_log_init()

WS_DLL_PUBLIC void ws_log_init | ( | void(*)(const char *, va_list ap) | vcmdarg_err,
|  | const char * | console_title
| ) |  |

Initialize the logging system.

Must be called at startup before using the log API. If provided, vcmdarg_err is used to print initialization errors, typically caused by misconfigured environment variables.

Parameters

  vcmdarg_err | Optional callback for reporting initialization errors.
  console_title | String title if/when console is launched

## ◆ ws_log_init_with_writer()

WS_DLL_PUBLIC void ws_log_init_with_writer | ( | ws_log_writer_cb * | writer,
|  | void(*)(const char *, va_list ap) | vcmdarg_err,
|  | const char * | console_title
| ) |  |

Initialize the logging system with a custom writer.

Can be used instead of ws_log_init(). Takes an extra writer argument. If provided, this callback will be used instead of the default writer.

Parameters

  writer | Callback function to handle log output, or NULL for default.
  vcmdarg_err | Optional callback for reporting initialization errors.
  console_title | String title if/when console is launched

## ◆ ws_log_init_with_writer_and_data()

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(*)(const char *, va_list ap) | vcmdarg_err,
|  | const char * | console_title
| ) |  |

Initialize the logging system with a custom writer and user data.

Accepts a user data pointer in addition to the writer. This pointer will be provided to the writer with every invocation. If provided, free_user_data will be called during cleanup.

Parameters

  writer | Callback function to handle log output, or NULL for default.
  user_data | Pointer to user-defined data passed to the writer.
  free_user_data | Optional callback to free user_data during cleanup.
  vcmdarg_err | Optional callback for reporting initialization errors.
  console_title | String title if/when console is launched

## ◆ ws_log_is_wslog_arg()

WS_DLL_PUBLIC bool ws_log_is_wslog_arg | ( | int | arg | ) |

Determine if a command-line argument is used by wslog.

Useful for applications that strictly validate command-line arguments but should delegate logging-related options to wslog instead of handling them directly.

Parameters

  arg | Argument index or identifier to check.

Returns
  True if the argument is recognized by wslog; false otherwise.

## ◆ ws_log_level_to_string()

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.

Parameters

  level | Log level as an enum value.

Returns
  Corresponding string name for the log level (e.g., "info", "debug").

## ◆ ws_log_msg_is_active()

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.

Returns true if a message with the specified domain and log level will be printed according to the current logging configuration.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level to check.

Returns
  True if the message would be logged; false otherwise.

## ◆ ws_log_parse_args()

WS_DLL_PUBLIC int ws_log_parse_args | ( | int * | argc_ptr,
|  | char * | argv[],
|  | const char * | optstring,
|  | const struct ws_option * | long_options,
|  | void(*)(const char *, va_list ap) | vcmdarg_err,
|  | int | exit_failure
| ) |  |

Parse command-line arguments for log options.

Parses standard and extended command-line options related to logging. Returns zero if all options are valid, or a non-zero value if one or more invalid options are encountered.

Parameters

  argc_ptr | Pointer to argument count (may be updated).
  argv | Argument vector.
  optstring | Short option string (as used by getopt).
  long_options | Array of extended options.
  vcmdarg_err | Callback for reporting invalid option errors.
  exit_failure | Exit code to use if parsing fails fatally.

Returns
  0 on success, non-zero on error.

## ◆ ws_log_print_usage()

WS_DLL_PUBLIC void ws_log_print_usage | ( | FILE * | fp | ) |

Print usage information for logging-related command-line options.

Writes a summary of supported logging options to the specified file, typically used for help or diagnostic output.

Parameters

  fp | File pointer to write usage information to.

## ◆ ws_log_set_debug_filter()

WS_DLL_PUBLIC void ws_log_set_debug_filter | ( | const char * | str_filter | ) |

Set a debug filter from a string.

Enables debug level output for all domains listed in the filter, regardless of the global log level and domain filter. If the filter is negated, debug (and below) output will be disabled for the listed domains, while others remain unaffected.

Parameters

  str_filter | String specifying domains for debug filtering.

## ◆ ws_log_set_domain_filter()

WS_DLL_PUBLIC void ws_log_set_domain_filter | ( | const char * | domain_filter | ) |

Set a domain filter from a string.

The domain filter is a case-insensitive list separated by ',' or ';'. Only domains matching the filter will generate output; all others are muted. Filter expressions can be prefixed with '!' to invert the match, causing only non-matching domains to generate output.

Parameters

  domain_filter | String containing domain filter expressions.

## ◆ ws_log_set_fatal_domain_filter()

WS_DLL_PUBLIC void ws_log_set_fatal_domain_filter | ( | const char * | domain_filter | ) |

Set a fatal domain filter from a string.

The domain filter is a case-insensitive list separated by ',' or ';'. Domains included in the filter will cause the program to abort when logged.

Parameters

  domain_filter | String containing fatal domain filter expressions.

## ◆ ws_log_set_fatal_level()

WS_DLL_PUBLIC enum ws_log_level ws_log_set_fatal_level | ( | enum ws_log_level | level | ) |

Set the fatal log level.

Sets the log level at which calls to ws_log() will abort the program. The argument can be LOG_LEVEL_ERROR, LOG_LEVEL_CRITICAL, or LOG_LEVEL_WARNING. LOG_LEVEL_ERROR is always treated as fatal.

Parameters

  level | Log level to set as fatal.

Returns
  The active fatal log level, or LOG_LEVEL_NONE if invalid.

## ◆ ws_log_set_fatal_level_str()

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.

Same as ws_log_set_fatal_level(), but accepts the strings "error", "critical", or "warning" (case insensitive) as arguments.

Parameters

  str_level | String representation of the fatal log level.

Returns
  The active fatal log level, or LOG_LEVEL_NONE if invalid.

## ◆ ws_log_set_level()

WS_DLL_PUBLIC enum ws_log_level ws_log_set_level | ( | enum ws_log_level | level | ) |

Set the active log level.

Sets the global log level to the specified level. Returns the active log level or LOG_LEVEL_NONE if the input level is invalid.

Parameters

  level | Log level to activate.

Returns
  The active log level or LOG_LEVEL_NONE if invalid.

## ◆ ws_log_set_level_str()

WS_DLL_PUBLIC enum ws_log_level ws_log_set_level_str | ( | const char * | str_level | ) |

Set the active log level from a string.

Accepts string representations of log levels: "error", "critical", "warning", "message", "info", "debug", and "noisy" (case insensitive). Returns the new active log level or LOG_LEVEL_NONE if the string is invalid.

Parameters

  str_level | Log level as a string.

Returns
  The active log level or LOG_LEVEL_NONE if invalid.

## ◆ ws_log_set_noisy_filter()

WS_DLL_PUBLIC void ws_log_set_noisy_filter | ( | const char * | str_filter | ) |

Set a noisy filter from a string.

Works like ws_log_set_debug_filter(), but applies to the "noisy" log level.

Parameters

  str_filter | String specifying domains for noisy level filtering.

## ◆ ws_log_set_writer()

WS_DLL_PUBLIC void ws_log_set_writer | ( | ws_log_writer_cb * | writer | ) |

Set the active log writer.

The parameter 'writer' can be NULL to use the default writer.

Parameters

  writer | Callback function to handle log output, or NULL for default.

## ◆ ws_log_set_writer_with_data()

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.

The parameter 'writer' can be NULL to use the default writer. Accepts an extra user_data parameter that will be passed to the log writer.

Parameters

  writer | Callback function to handle log output, or NULL for default.
  user_data | Pointer to user-defined data passed to the writer.
  free_user_data | Optional callback to free user_data when no longer needed.

## ◆ ws_log_utf8_full()

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.

Emits a log message for the specified domain and level, including source file name, line number, and function name. The message is provided as a UTF-8 string with explicit length and optional end pointer for partial or bounded output.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  string | UTF-8 encoded message string.
  length | Length of the message string in bytes.
  endptr | Optional pointer to the end of the message range.

## ◆ ws_log_write_always_full()

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,
|  |  | ...
| ) |  |

Emit a log message unconditionally with full source context.

This auxiliary function behaves like ws_log_full(), but skips domain/level filtering to avoid redundant activation checks. It should only be used when a prior call to ws_log_msg_is_active() confirms the message should be logged.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  format | printf-style format string for the log message.
  ... | Variable arguments matching the format string.

## ◆ ws_logv()

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.

This function emits a log message for the specified domain and level, using a printf-style format string and a va_list for arguments.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  format | printf-style format string for the log message.
  ap | va_list containing arguments for the format string.

## ◆ ws_logv_full()

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.

This function emits a log message for the specified domain and level, including source file name, line number, and function name for context. The message is constructed using a printf-style format string and a va_list.

Parameters

  domain | Logging domain or subsystem name.
  level | Log severity level.
  file | Source file name where the log originated.
  line | Line number in the source file.
  func | Function name where the log was generated.
  format | printf-style format string for the log message.
  ap | va_list containing arguments for the format string.