#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"

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))
	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))
	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))
	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,...) G_GNUC_PRINTF(3
	Output a formatted message to the log.

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.

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_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,...) G_GNUC_PRINTF(6
	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,...) G_GNUC_PRINTF(6
	Emit a log message unconditionally with full source context.

WS_DLL_PUBLIC void 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

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,...) G_GNUC_PRINTF(6

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

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

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.

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

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.

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

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.

◆ 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_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_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.

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ _LOG_IF_ACTIVE

◆ LONGOPT_WSLOG

◆ ws_critical

◆ ws_debug

◆ WS_DEBUG_HERE

◆ ws_error

◆ ws_info

◆ ws_log_buffer

◆ ws_log_utf8

◆ ws_message

◆ ws_noisy

◆ WS_NOT_IMPLEMENTED

◆ ws_warning

Typedef Documentation

◆ ws_log_writer_cb

◆ ws_log_writer_free_data_cb

Enumeration Type Documentation

◆ ws_log_console_open_pref

Function Documentation

◆ ws_log()

◆ ws_log_add_custom_file()

◆ ws_log_buffer_full()

◆ ws_log_console_writer()

◆ ws_log_console_writer_set_use_stdout()

◆ ws_log_fatal_full()

◆ ws_log_file_writer()

◆ ws_log_full()

◆ ws_log_get_level()

◆ ws_log_init()

◆ ws_log_init_with_writer()

◆ ws_log_init_with_writer_and_data()

◆ ws_log_is_wslog_arg()

◆ ws_log_level_to_string()

◆ ws_log_msg_is_active()

◆ ws_log_parse_args()

◆ ws_log_print_usage()

◆ ws_log_set_debug_filter()

◆ ws_log_set_domain_filter()

◆ ws_log_set_fatal_domain_filter()

◆ ws_log_set_fatal_level()

◆ ws_log_set_fatal_level_str()

◆ ws_log_set_level()

◆ ws_log_set_level_str()

◆ ws_log_set_noisy_filter()

◆ ws_log_set_writer()

◆ ws_log_set_writer_with_data()

◆ ws_log_utf8_full()

◆ ws_log_write_always_full()

◆ ws_logv()

◆ ws_logv_full()