Message Logging

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

## cx_critical()

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

## cx_error()

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

## cx_log()

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

## cx_log_default_handler()

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

## cx_log_get_domain_count()

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.

## cx_log_get_domain_name()

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

## cx_log_remove_handler()

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_set_always_fatal()

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_set_default_handler()

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_set_fatal_mask()

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.

## cx_log_set_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.

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

## cx_logv()

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

## cx_message()

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

## cx_print()

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_set_handler()

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

## cx_printerr()

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_printerr_set_handler()

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

## cx_warning()

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