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>

Go to the source code of this file.

Classes
struct	ws_log_manifest_t

Macros
#define	_LOG_DOMAIN   ""
#define	_LOG_DEBUG_ENABLED   false
#define	LOG_HKCU_CONSOLE_OPEN   "ConsoleOpen"
#define	LOG_ARGS_NOEXIT   -1
#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(...)
#define	ws_critical(...)    _LOG_FULL(true, LOG_LEVEL_CRITICAL, __VA_ARGS__)
#define	ws_warning(...)    _LOG_FULL(true, LOG_LEVEL_WARNING, __VA_ARGS__)
#define	ws_message(...)    _LOG_SIMPLE(true, LOG_LEVEL_MESSAGE, __VA_ARGS__)
#define	ws_info(...)    _LOG_SIMPLE(true, LOG_LEVEL_INFO, __VA_ARGS__)
#define	ws_debug(...)    _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_DEBUG, __VA_ARGS__)
#define	ws_noisy(...)    _LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_NOISY, __VA_ARGS__)
#define	WS_DEBUG_HERE(...)    _LOG_FULL(true, LOG_LEVEL_ECHO, __VA_ARGS__)
#define	WS_NOT_IMPLEMENTED()    ws_error("Not implemented yet")
#define	ws_log_utf8(str, len, endptr)
#define	ws_log_buffer(buf, size, msg)

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 }

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)
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)
WS_DLL_PUBLIC void	ws_log_console_writer_set_use_stdout (bool use_stdout)
WS_DLL_PUBLIC WS_RETNONNULL const char *	ws_log_level_to_string (enum ws_log_level level)
WS_DLL_PUBLIC bool	ws_log_msg_is_active (const char *domain, enum ws_log_level level)
WS_DLL_PUBLIC enum ws_log_level	ws_log_get_level (void)
WS_DLL_PUBLIC enum ws_log_level	ws_log_set_level (enum ws_log_level level)
WS_DLL_PUBLIC enum ws_log_level	ws_log_set_level_str (const char *str_level)
WS_DLL_PUBLIC void	ws_log_set_domain_filter (const char *domain_filter)
WS_DLL_PUBLIC void	ws_log_set_fatal_domain_filter (const char *domain_filter)
WS_DLL_PUBLIC void	ws_log_set_debug_filter (const char *str_filter)
WS_DLL_PUBLIC void	ws_log_set_noisy_filter (const char *str_filter)
WS_DLL_PUBLIC enum ws_log_level	ws_log_set_fatal_level (enum ws_log_level level)
WS_DLL_PUBLIC enum ws_log_level	ws_log_set_fatal_level_str (const char *str_level)
WS_DLL_PUBLIC void	ws_log_set_writer (ws_log_writer_cb *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)
WS_DLL_PUBLIC int	ws_log_parse_args (int *argc_ptr, char *argv[], void(*vcmdarg_err)(const char *, va_list ap), int exit_failure)
WS_DLL_PUBLIC void	ws_log_init (const char *progname, void(*vcmdarg_err)(const char *, va_list ap))
WS_DLL_PUBLIC void	ws_log_init_with_writer (const char *progname, ws_log_writer_cb *writer, void(*vcmdarg_err)(const char *, va_list ap))
WS_DLL_PUBLIC void	ws_log_init_with_writer_and_data (const char *progname, 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))
WS_DLL_PUBLIC void	ws_log (const char *domain, enum ws_log_level level, const char *format,...) G_GNUC_PRINTF(3
WS_DLL_PUBLIC void WS_DLL_PUBLIC void	ws_logv (const char *domain, enum ws_log_level level, const char *format, va_list ap)
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
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)
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
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)
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)
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
WS_DLL_PUBLIC void WS_DLL_PUBLIC void	ws_log_add_custom_file (FILE *fp)
WS_DLL_PUBLIC void	ws_log_print_usage (FILE *fp)

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)

ws_critical

#define ws_critical

(

...

)

_LOG_FULL(true, LOG_LEVEL_CRITICAL, __VA_ARGS__)

Logs with "critical" level.

Accepts a format string and includes the file and function name.

ws_debug

#define ws_debug

(

...

)

_LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_DEBUG, __VA_ARGS__)

Logs with "debug" level.

Accepts a format string and includes the file and function name.

WS_DEBUG_HERE

#define WS_DEBUG_HERE

(

...

)

_LOG_FULL(true, LOG_LEVEL_ECHO, __VA_ARGS__)

Used for temporary debug print outs, always active.

ws_error

#define ws_error

(

...

)

Value:

        ws_log_fatal_full(_LOG_DOMAIN, LOG_LEVEL_ERROR, \
                            __FILE__, __LINE__, __func__, __VA_ARGS__)

Logs with "error" level.

Accepts a format string and includes the file and function name.

"error" is always fatal and terminates the program with a coredump.

ws_info

#define ws_info

(

...

)

_LOG_SIMPLE(true, LOG_LEVEL_INFO, __VA_ARGS__)

Logs with "info" level.

Accepts a format string and does not include the file and function name (use ws_log_full instead).

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)

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)

ws_message

#define ws_message

(

...

)

_LOG_SIMPLE(true, LOG_LEVEL_MESSAGE, __VA_ARGS__)

Logs with "message" level.

Accepts a format string and does not include the file and function name (use ws_log_full instead). This is the default log level.

ws_noisy

#define ws_noisy

(

...

)

_LOG_FULL(_LOG_DEBUG_ENABLED, LOG_LEVEL_NOISY, __VA_ARGS__)

Logs with "noisy" level.

Accepts a format string and includes the file and function name.

ws_warning

#define ws_warning

(

...

)

_LOG_FULL(true, LOG_LEVEL_WARNING, __VA_ARGS__)

Logs with "warning" level.

Accepts a format string and includes the file and function name.

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.

Function Documentation

ws_log()

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

This function is called to output a message to the log.

Takes a format string and a variable number of arguments.

ws_log_add_custom_file()

WS_DLL_PUBLIC void WS_DLL_PUBLIC void ws_log_add_custom_file

(

FILE *

fp

)

Define an auxiliary file pointer where messages should be written.

This file, if set, functions in addition to the registered or default log writer.

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
	)

This function is called to log a buffer (bytes array).

Accepts an optional 'msg' argument to provide a description.

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.

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

This function is called to output a message to the log.

In addition to the message this function accepts file/line/function information.

ws_log_get_level()

WS_DLL_PUBLIC enum ws_log_level ws_log_get_level

(

void

)

Return the currently active log level.

ws_log_init()

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

Initializes the logging code.

Must be called at startup before using the log API. If provided vcmdarg_err is used to print initialization errors. This usually means a misconfigured environment variable.

ws_log_init_with_writer()

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

Initializes the logging code.

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

ws_log_init_with_writer_and_data()

WS_DLL_PUBLIC void ws_log_init_with_writer_and_data	(	const char *	progname,
		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
	)

Initializes the logging code.

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.

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 level to its string representation.

ws_log_msg_is_active()

WS_DLL_PUBLIC bool ws_log_msg_is_active	(	const char *	domain,
		enum ws_log_level	level
	)

Checks if a domain and level combination generate output.

Returns true if a message will be printed for the domain/level combo.

ws_log_parse_args()

WS_DLL_PUBLIC int ws_log_parse_args	(	int *	argc_ptr,
		char *	argv[],
		void(*)(const char *, va_list ap)	vcmdarg_err,
		int	exit_failure
	)

Parses the command line arguments for log options.

Returns zero for no error, non-zero for one or more invalid options.

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.

A debug filter lists all domains that should have debug level output turned on, regardless of the global log level and domain filter. If negated then debug (and below) will be disabled and the others unaffected by the filter.

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.

Domain filter is a case insensitive list separated by ',' or ';'. Only the domains in the filter will generate output; the others will be muted. Filter expressions can be preceded by '!' to invert the sense of the match. In this case only non-matching domains will generate output.

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.

Domain filter is a case insensitive list separated by ',' or ';'. Domains in the filter will cause the program to abort.

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. Level LOG_LEVEL_ERROR is always fatal.

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(), but accepts the strings "error", critical" or "warning" instead as arguments.

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. Returns the active level or LOG_LEVEL_NONE if level is 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.

String levels are "error", "critical", "warning", "message", "info", "debug" and "noisy" (case insensitive). Returns the new log level or LOG_LEVEL NONE if the string representation is 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.

Same as ws_log_set_debug_filter() for "noisy" level.

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.

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.

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.

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

Auxiliary function to write custom logging functions.

This function is the same as ws_log_full() but does not perform any domain/level filtering to avoid a useless double activation check. It should only be used in conjunction with a pre-check using ws_log_msg_is_active().

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
	)

This function is called to output a message to the log.

Takes a format string and a 'va_list'.

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
	)

This function is called to output a message to the log.

In addition to the message this function accepts file/line/function information.