Logger

The logging system provides a very basic mechanism to write messages to different types of streams. It is used by all the error and debug reporting facilities in Error Handling and Debugging, and therefore aims to be as robust as possible. If any error occurs during one of the logger functions, an error will be printed to stderr. If a logger is unsuccessful at writing the log message to the log stream then it will log the message to stdout. Also see Initialization, Finalization and Logging.

Summary

s_logger_file_new	Create a new file stream logger.
s_logger_console_new	Create a new console stream logger.
s_logger_null_new	Create a new null logger.
s_logger_write	Format and write the given logging event information to the logger.
s_logger_vwrite	Format and write the given logging event information to the logger (called with va_list).
s_logger_destroy	Destroy the given logger’s associated resources.
s_log_event_str	Get a string representation of the given log event level.

Definition

typedef struct s_logger

The s_logger structure definition.

The logger consists of private data which can be anything required by the specific implementation, as it is only defined as an opaque type. The different logger implementations must implement the function pointers as described. If any error occurs during one of the logger functions, the logger must try and continue and print the error to stderr.

s_logger Structure

Logger Creators

Three loggers are provided, one logging to file, one to a console and a null logger. The loggers must be freed by first calling s_logger_destroy() to free any private data of the logger, and then a call to S_FREE to free the logger itself.

s_logger *s_logger_file_new(const char *path)

Create a new file stream logger.

The logging message will be in the standard layout format.

Parameters:

• path –

  The full path and file name of the file which to log to. If the file already exists, then it will be overwritten.

Return:

Pointer to newly created file stream logger, or NULL on error.

Note:

Only thread safe if compiled with threading library, and whether the standard ISO C vfprintf() function is thread-safe, see Threads Abstraction.

See also:

File Stream, Standard

s_logger *s_logger_console_new(s_bool log_to_stdout)

Create a new console stream logger.

The logging message will be in the standard layout format.

Parameters:

• log_to_stdout –

  If TRUE then logging will be to stdout, otherwise streaming will be to stderr.

Return:

Pointer to newly created console stream logger, or NULL on error.

Note:

Only thread safe if compiled with threading library, and whether the standard ISO C vfprintf() function is thread-safe, see Threads Abstraction.

See also:

Console Stream, Standard

s_logger *s_logger_null_new(void)

Create a new null logger.

A null logger does not log any messages.

Return:Pointer to newly created null logger, or NULL on error. Note:The null logger must be destroyed (s_logger_destroy) and freed in the same manner as the other loggers.

Standard Layout Format

The standard layout for the file and console loggers define the format of the printed messages. There are two different formats, one for error messages and one for debugging/warning messages.

The error messages layout is as follows:

Date & Time [Logging event level¹ (Error message²) Thread id³] User message (in function ‘Function name⁴‘, File name⁴, File line number⁴)

where:

1. Derived automatically from s_log_event
2. Derived automatically from s_erc
3. Only if compiled with threads
4. Optional

For example, the following will be printed with all the above information available:

Wed 18 May 2011 11:58:41 SAST [ERROR (Memory error) 10] Failed to allocate object memory (in function 'func', /home/nobody/test.c, 121)

The debugging/warning messages layout is as follows:

Date & Time [Debugging/warning message type¹ Thread id²] User message

where:

1. Derived automatically from s_log_event and s_dbg_lvl
2. Only if compiled with threads

For example, the following will be printed with all the above information available:

Wed 18 May 2011 11:58:41 SAST [TRACE 10] value = 20.321

Logging Functions

s_erc s_logger_write(const s_logger *logger, s_log_event level, const char *error_msg, const char *func_name, const char *file_name, int line_num, const char *user_msg, ...)

Format and write the given logging event information to the logger.

Parameters:

• logger –

  The logger to write to.

• level –

  The event level.

• error_msg –

  As defined by s_erc.

• func_name –

  Calling function name.

• file_name –

  Calling function file name.

• line_num –

  Calling line number in function.

• user_msg –

  A format string specifying the string to write and the format of the variable length argument list. Same as the the standard printf() function.

Return:

Error code.

s_erc s_logger_vwrite(const s_logger *logger, s_log_event level, const char *error_msg, const char *func_name, const char *file_name, int line_num, const char *user_msg, va_list argp)

Format and write the given logging event information to the logger (called with va_list).

Equivalent to the s_logger_write except that it is called with a va_list instead of a variable number of arguments, same as the standard function vprintf().

Parameters:

• logger –

  The logger to write to.

• level –

  The event level.

• error_msg –

  As defined by s_erc.

• func_name –

  Calling function name.

• file_name –

  Calling function file name.

• line_num –

  Calling line number in function.

• user_msg –

  A format string specifying the string to write and the format of the arguments in the va_list.

• argp –

  The va_list, see the standard function ISO C vprintf(). The value of argp is undefined after the call to this function.

Return:

Error code.

Logger Destroyer

s_erc s_logger_destroy(s_logger *logger)

Destroy the given logger’s associated resources.

The logger must still be free’d with S_FREE after this call.

Parameters:

• logger –

  The logger object’s resources to destroy.

Return:

error Error code.

Note:

Thread-safety is dependent on the underlying implementation.

Logging Events

Logging event definitions. The log events defines the type of information that will be output to the log.

typedef enum s_log_event

Logging event level defintions.

Follows log4j Log levels (http://en.wikipedia.org/wiki/Log4j).

Values:

• S_RESERVED_EVENT = 0 -

  Reserved. Not to be used.

• S_FATAL_EVENT = 1 -

  Severe errors that cause premature termination. [FATAL] in layout.

• S_ERROR_EVENT = 2 -

  Other run time errors or unexpected conditions. [ERROR] in layout.

• S_WARN_EVENT = 3 -

  Undesirable/unexpected run time situations, but not necessarily “wrong”. [WARN] in layout.

• S_INFO_EVENT = 4 -

  Interesting run time events (start up/shutdown). [INFO] in layout.

• S_DEBUG_EVENT = 5 -

  Detailed information on the flow through the system. [DEBUG] in layout.

• S_TRACE_EVENT = 6 -

  More detailed information. [TRACE] in layout.

char *s_log_event_str(s_log_event level)

Get a string representation of the given log event level.

Parameters:

• level –

  The given log event level.

Return:

Pointer to string representation of given log event level. If the error code is unknown then “UNKNOWN EVENT” is returned.

Note:

Caller is responsible for returned character buffer’s memory.

Thread-safe.