Central logging functions for the library and calling programs. More...

Data Structures
struct	MSLogEntry
	Log registry entry. More...

struct	MSLogRegistry
	Log message registry. More...

struct	MSLogParam
	Logging parameters. Callers should not modify these values directly and generally should not need to access them. More...

Macros
#define	MAX_LOG_MSG_LENGTH 200

#define	MSLogRegistry_INITIALIZER
	Initialializer for MSLogRegistry.

#define	MSLogParam_INITIALIZER
	Initialializer for MSLogParam.

#define	ms_log(level, ...) ms_rlog(__func__, level, __VA_ARGS__)
	Wrapper for ms_rlog(), call as ms_log (level, format, ...)

#define	ms_log_l(logp, level, ...) ms_rlog_l(logp, __func__, level, __VA_ARGS__)
	Wrapper for ms_rlog_l(), call as ms_log_l (logp, level, format, ...)

#define	ms_loginit(log_print, logprefix, diag_print, errprefix) ms_rloginit(log_print, logprefix, diag_print, errprefix, 0)
	Convenience wrapper for ms_rloginit(), omitting max messages, disabling registry.

#define	ms_loginit_l(logp, log_print, logprefix, diag_print, errprefix) ms_rloginit_l(logp, log_print, logprefix, diag_print, errprefix, 0)
	Convenience wrapper for ms_rloginit_l(), omitting max messages, disabling registry.

Functions
int	ms_rlog (const char function, int level, const char format,...)
	Register log message using global logging parameters.

int	ms_rlog_l (MSLogParam logp, const char function, int level, const char *format,...)
	Register log message using specified logging parameters.

void	ms_rloginit (void(log_print)(const char ), const char logprefix, void(diag_print)(const char ), const char errprefix, int maxmessages)
	Initialize the global logging parameters.

MSLogParam *	ms_rloginit_l (MSLogParam logp, void(log_print)(const char ), const char logprefix, void(diag_print)(const char ), const char *errprefix, int maxmessages)
	Initialize specified MSLogParam logging parameters.

int	ms_rlog_emit (MSLogParam *logp, int count, int context)
	Emit, aka send to print functions, messages from log registry.

int	ms_rlog_free (MSLogParam *logp)
	Free, without emitting, all messages from log registry.

Detailed Description

Central logging functions for the library and calling programs.

This central logging facility is used for all logging performed by the library. Calling programs may also wish to log messages via the same facility for consistency.

The logging can be configured to send messages to arbitrary functions, referred to as log_print() and diag_print(). This allows output to be re-directed to other logging systems if needed.

It is also possible to assign prefixes to log messages for identification, referred to as logprefix and errprefix.

Logging levels

Three message levels are recognized:

0 : Normal log messages, printed using log_print() with logprefix
1 : Diagnostic messages, printed using diag_print() with logprefix
2+ : Error messages, printed using diag_print() with errprefix

It is the task of the ms_rlog() and ms_rlog_l() functions to format a message using printf conventions and pass the formatted string to the appropriate printing function. The convenience macros ms_log() and ms_log_l() can be used to automatically set the calling function name.

Log Registry

The log registry facility allows a calling program to disable error (and warning) output from the library and either inspect it or emit (print) as desired.

By default log messages are sent directly to the printing functions. Optionally, error and warning messages (levels 1 and 2) can be accumulated in a log-registry. Verbose output messages (level 0) are not accumulated in the registry. The registry is enabled by setting the maxmessages argument of either ms_rloginit() or ms_rloginit_l(). Messages can be emitted, aka printed, using ms_rlog_emit() and cleared using ms_rlog_free(). Alternatively, the MSLogRegistry associated with a MSLogParam (or the global parameters at gMSLogParam).

See Read miniSEED from files for a simple example of error and warning message registry usage.

Logging in Threads

By default the library is compiled in a mode where each thread of a multi-threaded program will have it's own, default logging parameters. If you wish to change the default printing functions, message prefixes, or enable the log registry, this must be done per-thread.

The library can be built with the LIBMSEED_NO_THREADING variable defined, resulting in a mode where there are global parameters for all threads. In general this should not be used unless the system does not support the necessary thread-local storage directives.

Message on Error

Functions marked as MessageOnError log a message when returning an error status or logging a warning (log levels 1 and 2). This indication can be useful when error and warning messages are retained in log-registry.

Data Structure Documentation

◆ MSLogEntry

struct MSLogEntry

Log registry entry.

See also: ms_rlog(); ms_rlog_l()

Data Fields
int	level	Message level.
char	function[30]	Function generating the message.
char	message[MAX_LOG_MSG_LENGTH]	Log, warning or error message.
struct MSLogEntry *	next

◆ MSLogRegistry

struct MSLogRegistry

Log message registry.

See also: ms_rlog(); ms_rlog_l()

Data Fields
int	maxmessages
int	messagecnt
MSLogEntry *	messages

◆ MSLogParam

struct MSLogParam

Logging parameters. Callers should not modify these values directly and generally should not need to access them.

See also: ms_loginit()

Data Fields
void()(const char )	log_print	Function to call for regular messages.
const char *	logprefix	Message prefix for regular and diagnostic messages.
void()(const char )	diag_print	Function to call for diagnostic and error messages.
const char *	errprefix	Message prefix for error messages.
MSLogRegistry	registry	Message registry.

Macro Definition Documentation

◆ MAX_LOG_MSG_LENGTH

#define MAX_LOG_MSG_LENGTH 200

Maximum length of log messages in bytes

◆ MSLogRegistry_INITIALIZER

#define MSLogRegistry_INITIALIZER

Value:

  {                                                      \
    .maxmessages = 0, .messagecnt = 0, .messages = NULL  \
  }

Initialializer for MSLogRegistry.

◆ MSLogParam_INITIALIZER

#define MSLogParam_INITIALIZER

Value:

  {                                        \
    .log_print = NULL, .logprefix = NULL,  \
    .diag_print = NULL, .errprefix = NULL, \
    .registry = MSLogRegistry_INITIALIZER  \
  }

Initialializer for MSLogParam.

Function Documentation

◆ ms_rlog()

int ms_rlog	(	const char *	function,
		int	level,
		const char *	format,
			... )

extern

Register log message using global logging parameters.

It is convenient to call this function via the ms_log() macro, which sets the calling function automatically.

Three message levels are recognized, see logging-levels for more information.

This function builds the log/error message and passes to it to the appropriate print function. If custom printing functions have not been defined, messages will be printed with fprintf(), log messages to stdout and error messages to stderr.

If the log/error prefixes have been set they will be pre-pended to the message. If no custom log prefix is set none will be included. If no custom error prefix is set "Error: " will be included.

A trailing newline character is for error messages is removed if the message is added to the log registry.

All messages will be truncated at the MAX_LOG_MSG_LENGTH, this includes any prefix.

Parameters

[in]	function	Name of function registering log message
[in]	level	Message level
[in]	format	Message format in printf() style
[in]	...	Message format variables

Returns: The number of characters formatted on success, and a negative value on error..

◆ ms_rlog_l()

int ms_rlog_l	(	MSLogParam *	logp,
		const char *	function,
		int	level,
		const char *	format,
			... )

extern

Register log message using specified logging parameters.

It is convenient to call this function via the ms_log_l() macro, which sets the calling function automatically.

The function uses logging parameters specified in the supplied MSLogParam. This reentrant capability allows using different parameters in different parts of a program or different threads.

Three message levels are recognized, see logging-levels for more information.

This function builds the log/error message and passes to it to the appropriate print function. If custom printing functions have not been defined, messages will be printed with fprintf(), log messages to stdout and error messages to stderr.

If the log/error prefixes have been set they will be pre-pended to the message. If no custom log prefix is set none will be included. If no custom error prefix is set "Error: " will be included.

A trailing newline character is for error messages is removed if the message is added to the log registry.

All messages will be truncated at the MAX_LOG_MSG_LENGTH, this includes any prefix.

Parameters

[in]	logp	Pointer to MSLogParam to use for this message
[in]	function	Name of function registering log message
[in]	level	Message level
[in]	format	Message format in printf() style
[in]	...	Message format variables

Returns: The number of characters formatted on success, and a negative value on error.

◆ ms_rloginit()

void ms_rloginit	(	void(*	log_print )(const char *),
		const char *	logprefix,
		void(*	diag_print )(const char *),
		const char *	errprefix,
		int	maxmessages )

extern

Initialize the global logging parameters.

Any message printing functions indicated must except a single argument, namely a string (const char *) that will contain the log message. If the function pointers are NULL, defaults will be used.

If the log and error prefixes have been set they will be pre-pended to the message. If the prefixes are NULL, defaults will be used.

If maxmessages is greater than zero, warning and error (level >= 1) messages will be accumulated in a message registry. Once the maximum number of messages have accumulated, the oldest messages are discarded. Messages in the registry can be printed using ms_rlog_emit() or cleared using ms_rlog_free().

Parameters

[in]	log_print	Function to print log messages
[in]	logprefix	Prefix to add to log and diagnostic messages
[in]	diag_print	Function to print diagnostic and error messages
[in]	errprefix	Prefix to add to error messages
[in]	maxmessages	Maximum number of error/warning messages to store in registry

See also: ms_rlog(); ms_rlog_emit(); ms_rlog_free()

◆ ms_rloginit_l()

MSLogParam * ms_rloginit_l	(	MSLogParam *	logp,
		void(*	log_print )(const char *),
		const char *	logprefix,
		void(*	diag_print )(const char *),
		const char *	errprefix,
		int	maxmessages )

extern

Initialize specified MSLogParam logging parameters.

If the logging parameters have not been initialized (logp == NULL), new parameter space will be allocated.

Any message printing functions indicated must except a single argument, namely a string (const char *) that will contain the log message. If the function pointers are NULL, defaults will be used.

If the log and error prefixes have been set they will be pre-pended to the message. If the prefixes are NULL, defaults will be used.

If maxmessages is greater than zero, warning and error (level >= 1) messages will be accumulated in a message registry. Once the maximum number of messages have accumulated, the oldest messages are discarded. Messages in the registry can be printed using ms_rlog_emit() or cleared using ms_rlog_free().

Parameters

[in]	logp	MSLogParam logging parameters
[in]	log_print	Function to print log messages
[in]	logprefix	Prefix to add to log and diagnostic messages
[in]	diag_print	Function to print diagnostic and error messages
[in]	errprefix	Prefix to add to error messages
[in]	maxmessages	Maximum number of error/warning messages to store in registry

Returns: a pointer to the created/re-initialized MSLogParam struct on success and NULL on error.

See also: ms_rlog(); ms_rlog_emit(); ms_rlog_free()

◆ ms_rlog_emit()

int ms_rlog_emit	(	MSLogParam *	logp,
		int	count,
		int	context )

extern

Emit, aka send to print functions, messages from log registry.

Emit messages from the log registry, using the printing functions identified by the MSLogParam.

Messages are printed in order from earliest to latest.

The maximum number messages to emit, from most recent to earliest, can be limited using count. If the value is 0 all messages are emitted. If this limit is used and messages are left in the registry, it is highly recommended to either emit them soon or clear them with ms_rlog_free(). A common pattern would be to emit the last message (e.g. count of 1) and immediately free (discard) any remaining messages.

Parameters

[in]	logp	MSLogParam for this message or NULL for global parameters
[in]	count	Number of messages to emit, 0 to emit all messages
[in]	context	If non-zero include context by prefixing the function name (if available)

Returns: The number of message emitted on success, and a negative value on error.

See also: ms_rloginit(); ms_rlog_free()

◆ ms_rlog_free()

int ms_rlog_free ( MSLogParam * logp )

extern

Free, without emitting, all messages from log registry.

Parameters

[in] logp MSLogParam for this message or NULL for global parameters

Returns: The number of message freed on success, and a negative value on error.

Data Structures

Macros

Functions

Detailed Description

Logging levels

Log Registry

Logging in Threads

Message on Error

Data Structure Documentation

◆ MSLogEntry

◆ MSLogRegistry

◆ MSLogParam

Macro Definition Documentation

◆ MAX_LOG_MSG_LENGTH

◆ MSLogRegistry_INITIALIZER

◆ MSLogParam_INITIALIZER

Function Documentation

◆ ms_rlog()

◆ ms_rlog_l()

◆ ms_rloginit()

◆ ms_rloginit_l()

◆ ms_rlog_emit()

◆ ms_rlog_free()