Functions
cx_log_level_flags	cx_log_set_always_fatal (cx_log_level_flags mask)
	Set log levels to be always fatal.
cxsize	cx_log_get_domain_count (void)
	Get the number of registered log domains.
const cxchar *	cx_log_get_domain_name (cxsize position)
	Get the name of a log domain.
cx_log_level_flags	cx_log_set_fatal_mask (const cxchar *name, cx_log_level_flags fatal_mask)
	Sets the log message level which are fatal for a given domain.
cx_log_func	cx_log_set_default_handler (cx_log_func func)
	Set the default log handler.
cxuint	cx_log_set_handler (const cxchar *name, cx_log_level_flags levels, cx_log_func func, cxptr data)
	Set the log handler for a log domain.
void	cx_log_remove_handler (const cxchar *name, cxuint id)
	Remove a log handler from a domain.
void	cx_logv (const cxchar name, cx_log_level_flags level, const cxchar format, va_list args)
	Log a formatted message using a variable-length argument.
void	cx_log (const cxchar name, cx_log_level_flags level, const cxchar format,...)
	Log a formatted message.
void	cx_log_default_handler (const cxchar name, cx_log_level_flags level, const cxchar message, cxptr data)
	Default log handler.
cx_print_func	cx_print_set_handler (cx_print_func func)
	Set handler for message output.
void	cx_print (const cxchar *format,...)
	Output a formatted message via the print handler.
cx_print_func	cx_printerr_set_handler (cx_print_func func)
	Set handler for error message output.
void	cx_printerr (const cxchar *format,...)
	Output a formatted message via the error message handler.
void	cx_error (const cxchar *format,...)
	Log an error message.
void	cx_critical (const cxchar *format,...)
	Log a "critical" warning.
void	cx_warning (const cxchar *format,...)
	Log a warning.
void	cx_message (const cxchar *format,...)
	Log a normal message.

Detailed Description

The module implements a flexible logging facility. It can be customized to fit into the application environment. Log levels and functions can be defined and used in addition to or as replacement of the built in levels and log functions.

Synopsis:: #include <cxmessages.h>

Function Documentation

void cx_critical	(	const cxchar *	format,
			...
	)

Log a "critical" warning.

Parameters:

format	The format string.
...	Arguments to be inserted into the format string.

Returns:: Nothing.

This is a convenience function to log a message with level CX_LOG_LEVEL_CRITICAL, as specified by the format string format and the following list of arguments, via the installed log handler.

It is up to the application to decide which warnings are critical and which are not. To cause a termination of the application on critical warnings you may call cx_log_set_always_fatal().

See also:: cx_warning()

References cx_logv().

void cx_error	(	const cxchar *	format,
			...
	)

Log an error message.

Parameters:

format	The format string.
...	Arguments to be inserted into the format string.

Returns:: Nothing.

This is a convenience function to log an error message specified by the format string format and the following list of arguments via the installed log handler.

Error messages are always considered fatal, i.e. the application is immediately terminated by a call to abort() causing a core dump. Do not use this function for expected (recoverable) errors. This function should be used to indicate a bug (assertion failure) in the application.

See also:: cx_critical()

References cx_logv().

Referenced by cx_calloc(), cx_malloc(), cx_malloc_clear(), and cx_realloc().

void cx_log	(	const cxchar *	name,
		cx_log_level_flags	level,
		const cxchar *	format,
			...
	)

Log a formatted message.

Parameters:

name	Name of the log domain.
level	The message log level.
format	Format string defining output converstions.
...	Argument list.

The log message, as defined by the format string format and the corresponding argument list is logged with the level level, if it is enabled, using the log function set for the log domain name. given by the variable-length argument is formatted according to the All standard printf() conversion directives are supported.

References cx_logv().

void cx_log_default_handler	(	const cxchar *	name,
		cx_log_level_flags	level,
		const cxchar *	message,
		cxptr	data
	)

Default log handler.

Parameters:

name	The message's log domain name
level	Log level of the message
message	The message text
data	Extra data passed by the caller (ignored!)

Returns:: Nothing.

The default log handler, which is used if no log handler has been set by a call to cx_log_set_handler() for the combination domain name and log level level. The message text message is written to stdout, or stderr if the level is one of CX_LOG_LEVEL_ERROR, CX_LOG_LEVEL_CRITICAL and CX_LOG_LEVEL_WARNING. In addition, if the log level is fatal the program is aborted by a call to abort().

See also:: cx_log_set_handler()

References cx_program_get_name(), cx_string_append(), cx_string_delete(), cx_string_get(), cx_string_new(), cx_string_prepend(), and cx_string_sprintf().

cxsize cx_log_get_domain_count ( void )

Get the number of registered log domains.

Returns:: The number of currently registered log domains.

The function counts the registered log domains and returns the total number of log domains. The returned number may be 0 if no log domain was previously registered.

const cxchar* cx_log_get_domain_name ( cxsize position )

Get the name of a log domain.

Parameters:

position Index of the log domain to lookup.

Returns:: The function returns the name of the log domain, or NULL if position is out of range.

The function retrieves the name of the log domain registered at index position position. The valid range for position is from 0 to 1 less than the number of domains registered. If an invalid log domain is requested, i.e. no log domain has been previously registered for the given position, the function returns NULL.

See also:: cx_log_get_domain_count()

void cx_log_remove_handler	(	const cxchar *	name,
		cxuint	id
	)

Remove a log handler from a domain.

Parameters:

name	Name of the log domain.
id	Id number of the handler.

Removes the log handler, i.e. in principle the log function, registered with the id number id, from the list of log handlers for the log domain name.

References cx_free(), and cx_warning().

cx_log_level_flags cx_log_set_always_fatal ( cx_log_level_flags mask )

Set log levels to be always fatal.

Parameters:

mask	Log message level flags.

Returns:: Previous mask.

Log levels set in the log message level flags mask mask will always be treated as fatal. This applies only to the internally known log levels. User defined log levels are not taken into account.

In any case, the function forces errors to be fatal even if the error level was not set in mask. The priviously set mask is replaced by mask and is passed back to the caller as the return value.

cx_log_func cx_log_set_default_handler ( cx_log_func func )

Set the default log handler.

Parameters:

func	New handler function.

Returns:: The previously set print handler.

The function func is installed as the new default log handler function. Any message passed to cx_log() or cx_logv() is printed using this handler unless a domain and level specific handler has been set for the current message.

See also:: cx_log_set_handler()

cx_log_level_flags cx_log_set_fatal_mask	(	const cxchar *	name,
		cx_log_level_flags	fatal_mask
	)

Sets the log message level which are fatal for a given domain.

Parameters:

name	Name of the log domain.
fatal_mask	The log domains new fatal mask.

Returns:: Previously installed fatal mask for the domain.

The log message levels set in the flag mask fatal_mask are treated as being fatal for the log domain with the name name. Even if the error level is not set in fatal_mask the function forces errors to be fatal.

cxuint cx_log_set_handler	(	const cxchar *	name,
		cx_log_level_flags	levels,
		cx_log_func	func,
		cxptr	data
	)

Set the log handler for a log domain.

Parameters:

name	Name of the log domain.
levels	Log levels.
func	log function.
data	User data.

Returns:: The handler's id for this domain.

The log function func is set for the domain with the name name, applicable for the log levels given by the flag mask levels. If the log function func requires extra data this can be passed to func through the user data data.

References cx_malloc().

void cx_logv	(	const cxchar *	name,
		cx_log_level_flags	level,
		const cxchar *	format,
		va_list	args
	)

Log a formatted message using a variable-length argument.

Parameters:

name	Name of the log domain.
level	The message log level.
format	Format string defining output converstions.
args	Variable-length argument list.

The log message, as defined by the format string format and arguments given by the variable-length argument args is formatted according to the conversion directives present in the format string. All standard printf() conversion directives are supported.

The formatted message is logged for the level level, if it is enabled, using the log function set for the log domain name.

References cx_bits_find(), cx_free(), cx_strvdupf(), and cx_vsnprintf().

Referenced by cx_critical(), cx_error(), cx_log(), cx_message(), and cx_warning().

void cx_message	(	const cxchar *	format,
			...
	)

Log a normal message.

Parameters:

format	The format string.
...	Arguments to be inserted into the format string.

Returns:: Nothing.

This is a convenience function to log an ordinary message, as specified by the format string format and the following list of arguments, via the installed log handler.

References cx_logv().

void cx_print	(	const cxchar *	format,
			...
	)

Output a formatted message via the print handler.

Parameters:

format	The message format.
...	Argument list.

Returns:: Nothing.

The output message created from the format string format and the converted arguments from the argument list is output via the currently set print handler. The format string may contain all conversion directives supported by printf(). The default print handler outputs messages to stdout.

The cx_print() function should not be from within libraries for debugging messages, since it may be redirected by applications. Instead, libraries should use cx_log(), or the convenience functions cx_error(), cx_critical(), cx_warning() and cx_message().

See also:: cx_print_set_handler()

References cx_free(), and cx_strvdupf().

Referenced by cx_string_print().

cx_print_func cx_print_set_handler ( cx_print_func func )

Set handler for message output.

Parameters:

func	New handler function.

Returns:: The previously set print handler.

The function func is installed as the new message printing function. Any message passed to cx_print() is printed using this handler. The default print handler just outputs the message text to stdout.

See also:: cx_print()

void cx_printerr	(	const cxchar *	format,
			...
	)

Output a formatted message via the error message handler.

Parameters:

format	The message format.
...	Argument list.

Returns:: Nothing.

The output error message created from the format string format and the converted arguments from the argument list is output via the currently set error message handler. The format string may contain all conversion directives supported by printf(). The default error message handler outputs messages to stderr.

The cx_printerr() function should not be from within libraries for debugging messages, since it may be redirected by applications. Instead, libraries should use cx_log(), or the convenience functions cx_error(), cx_critical(), cx_warning() and cx_message().

See also:: cx_printerr_set_handler()

References cx_free(), and cx_strvdupf().

cx_print_func cx_printerr_set_handler ( cx_print_func func )

Set handler for error message output.

Parameters:

func	New handler function.

Returns:: The previously set error message handler.

The function func is installed as the new error message printing function. Any message passed to cx_printerr() is printed using this handler. The default print handler just outputs the error message text to stderr.

See also:: cx_printerr()

void cx_warning	(	const cxchar *	format,
			...
	)

Log a warning.

Parameters:

format	The format string.
...	Arguments to be inserted into the format string.

Returns:: Nothing.

This is a convenience function to log a warning message, as specified by the format string format and the following list of arguments, via the installed log handler.

See also:: cx_critical()

References cx_logv().

Referenced by cx_log_remove_handler(), and cx_memory_vtable_set().

Functions

Detailed Description

Function Documentation