C Standard Library Extensions  1.2
Functions
Message Logging

Functions

cx_log_level_flags cx_log_set_always_fatal (cx_log_level_flags mask)
 Set log levels to be always fatal. More...
 
cxsize cx_log_get_domain_count (void)
 Get the number of registered log domains. More...
 
const cxchar * cx_log_get_domain_name (cxsize position)
 Get the name of a log domain. More...
 
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. More...
 
cx_log_func cx_log_set_default_handler (cx_log_func func)
 Set the default log handler. More...
 
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. More...
 
void cx_log_remove_handler (const cxchar *name, cxuint id)
 Remove a log handler from a domain. More...
 
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. More...
 
void cx_log (const cxchar *name, cx_log_level_flags level, const cxchar *format,...)
 Log a formatted message. More...
 
void cx_log_default_handler (const cxchar *name, cx_log_level_flags level, const cxchar *message, cxptr data)
 Default log handler. More...
 
cx_print_func cx_print_set_handler (cx_print_func func)
 Set handler for message output. More...
 
void cx_print (const cxchar *format,...)
 Output a formatted message via the print handler. More...
 
cx_print_func cx_printerr_set_handler (cx_print_func func)
 Set handler for error message output. More...
 
void cx_printerr (const cxchar *format,...)
 Output a formatted message via the error message handler. More...
 
void cx_error (const cxchar *format,...)
 Log an error message. More...
 
void cx_critical (const cxchar *format,...)
 Log a "critical" warning. More...
 
void cx_warning (const cxchar *format,...)
 Log a warning. More...
 
void cx_message (const cxchar *format,...)
 Log a normal message. More...
 

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
formatThe 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
formatThe 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
nameName of the log domain.
levelThe message log level.
formatFormat 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
nameThe message's log domain name
levelLog level of the message
messageThe message text
dataExtra 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
positionIndex 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
nameName of the log domain.
idId 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
maskLog 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
funcNew 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
nameName of the log domain.
fatal_maskThe 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
nameName of the log domain.
levelsLog levels.
funclog function.
dataUser 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
nameName of the log domain.
levelThe message log level.
formatFormat string defining output converstions.
argsVariable-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
formatThe 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
formatThe 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
funcNew 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
formatThe 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
funcNew 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
formatThe 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().