Functions for simplified logging. More...

#include <stdarg.h>
#include <stdio.h>
#include "../dom.h"
#include "mem.h"

Macros
#define	JW_LOG_TRACE_FUNCTION_NO_ARGS jw_log(JW_LOG_TRACE, "entering: %s", __func__)

#define	JW_LOG_TRACE_FUNCTION(fmt, ...)

#define	JW_LOG_DOM_REF(level, dom, caption)

Typedefs
typedef void(*	jw_log_generator_fn) (const char *chunk, size_t len, jw_data_free_func free_fn, void arg)

typedef int(*	jw_log_vararg_function) (FILE stream, const char format, va_list ap)

Enumerations
enum	jw_loglevel { JW_LOG_NONE = 0, JW_LOG_ERROR, JW_LOG_WARN, JW_LOG_INFO, JW_LOG_VERBOSE, JW_LOG_DEBUG, JW_LOG_TRACE, JW_LOG_MEMTRACE }

Functions
JABBERWERX_API const char *	jw_log_level_name (jw_loglevel level)

JABBERWERX_API void	jw_log_set_function (jw_log_vararg_function fn)

JABBERWERX_API void	jw_log_set_level (jw_loglevel level)

JABBERWERX_API jw_loglevel	jw_log_get_level ()

JABBERWERX_API void	jw_log_set_ndc_enabled (bool enabled)

JABBERWERX_API int	jw_log_push_ndc (const char *fmt,...) __attribute__((__format__(__printf__

JABBERWERX_API int JABBERWERX_API void	jw_log_pop_ndc (int ndc_depth)

JABBERWERX_API void	jw_log (jw_loglevel level, const char *fmt,...) __attribute__((__format__(__printf__

JABBERWERX_API void JABBERWERX_API void	jw_log_err (jw_loglevel level, jw_err err, const char fmt,...) __attribute__((__format__(__printf__

JABBERWERX_API void JABBERWERX_API void JABBERWERX_API void	jw_log_dom (jw_loglevel level, jw_dom_node dom, const char fmt,...) __attribute__((__format__(__printf__

JABBERWERX_API void JABBERWERX_API void JABBERWERX_API void JABBERWERX_API void	jw_log_chunked (jw_loglevel level, jw_log_generator_fn generator_fn, void arg, const char fmt,...) __attribute__((__format__(__printf__

Detailed Description

Functions for simplified logging.

Copyrights

Macro Definition Documentation

#define JW_LOG_DOM_REF	(	level,
		dom,
		caption
	)

Value:

jw_log_dom((level), (dom), "%s(context: %p, ref: %p)", \
               (caption) ? (caption) : "",\
               (dom) ? (void *)jw_dom_get_context((dom)) : NULL, \
               (void *)(dom));

Macro to log an element, its context and reference. Restrictions detailed in jw_log_dom apply.

Parameters

[in]	level	The log level for this message.
[in]	dom	the element to be logged.
[in]	caption	string appended to dom information, may be NULL or empty

#define JW_LOG_TRACE_FUNCTION	(	fmt,
		...
	)

Value:

jw_log(JW_LOG_TRACE, "entering: %s; args=("fmt")", \

__func__ , __VA_ARGS__)

JW_LOG_TRACE

Definition: log.h:67

jw_log

JABBERWERX_API void jw_log(jw_loglevel level, const char *fmt,...) __attribute__((__format__(__printf__

Convenience macro for tracing a function entry with logged arguments. The space after func but before the comma is intentional as recommended at http://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html for compatibility

#define JW_LOG_TRACE_FUNCTION_NO_ARGS jw_log(JW_LOG_TRACE, "entering: %s", __func__)

Convenience macro for tracing a function entry where no arguments need to be logged

Typedef Documentation

typedef void(* jw_log_generator_fn) (const char **chunk, size_t *len, jw_data_free_func *free_fn, void *arg)

Signature of the log text generator function passed to jw_log_chunked(). No log message functions should be called from this function to avoid garbled output or infinite loops.

Invariant: chunk != NULL; len != NULL; free_fn != NULL

Parameters

[out]	chunk	A pointer to the fragment to append to the in-progress log message. The function will be called repeatedly until chunk is set to NULL. If len is not set or explicitly set to 0, *chunk is assumed to be a NULL-terminated string.
[out]	len	A pointer to the length of the fragment pointed to by chunk. If *chunk is NULL-terminated, this variable does not need to be set.
[out]	free_fn	A pointer to the function that will be called to free chunk. If chunk does not need freeing, *free_fn does not need to be set.
[in]	arg	The user-supplied pointer passed to jw_log_chunked().

typedef int(* jw_log_vararg_function) (FILE *stream, const char *format, va_list ap)

Function like vfprintf to be used for logging.

Note: Supplied function will be called three times for each log message; once for date/time/level preamble, once for the message and once for a trailing newline.

Parameters

stream	Output stream, always stderr.
format	Format string like vfprintf.
ap	Additional parameters to interpolate into {fmt}.

Return values

Number of bytes written.

Enumeration Type Documentation

enum jw_loglevel

Enumeration of defined log levels

Enumerator
JW_LOG_NONE	Log level that indicates no messages should be output
JW_LOG_ERROR	Logging error-level messages
JW_LOG_WARN	Logging warn-level messages
JW_LOG_INFO	Logging info-level messages
JW_LOG_VERBOSE	Logging verbose-level messages
JW_LOG_DEBUG	Logging debug-level messages
JW_LOG_TRACE	Logging trace-level messages
JW_LOG_MEMTRACE	Logging memory allocation-level messages

Function Documentation

JABBERWERX_API void jw_log	(	jw_loglevel	level,
		const char *	fmt,
			...
	)

Log at the given level to stderr.

All errors while logging are ignored (so this routine is not guaranteed to log). Extra parameters are injected into {fmt} using the rules from vfprintf.

Log messages are prepended with date/time and log level and appended with a newline; YYYY-MM-DDTHH-MM-SS[level]: {fmt}
Note: Not thread-safe with respect to the current log level.

Invariant: fmt != NULL

Parameters

[in]	level	The log level for this message. Note that JW_LOG_NONE is not a valid log level to pass to this function.
[in]	fmt	The printf-style format to log
[in]	...	Extra parameters to interpolate into {fmt}.

JABBERWERX_API void JABBERWERX_API void JABBERWERX_API void JABBERWERX_API void jw_log_chunked	(	jw_loglevel	level,
		jw_log_generator_fn	generator_fn,
		void *	arg,
		const char *	fmt,
			...
	)

Log a message with content provided by a generator function. The content from the generator function will appear immediately after the specified fmt, i.e.: "fmt<generator fn output>\n"

Note: Not thread-safe with respect to the current log level.

Parameters

[in]	level	The log level for this message. Note that JW_LOG_NONE is not a valid log level to pass to this function.
[in]	generator_fn	The generator function that will provide the log message content.
[in]	arg	The opaque pointer passed to the generator function.
[in]	fmt	The printf-style format to log. If NULL, equivalent to "".
[in]	...	Extra parameters to interpolate into {fmt}.

JABBERWERX_API void JABBERWERX_API void JABBERWERX_API void jw_log_dom	(	jw_loglevel	level,
		jw_dom_node *	dom,
		const char *	fmt,
			...
	)

Log a jw_dom_node element with extra information. dom and fmt may be NULL. Logs message "fmt(<serialized dom/>|(null))\n"

Note: Not thread-safe with respect to the current log level. Note: Resources are allocated and freed within this function. Failures are reported as "dom could not be serialized" in the log message.

Parameters

[in]	level	The log level for this message. Note that JW_LOG_NONE is not a valid log level to pass to this function.
[in]	dom	The element to be logged. May be NULL. If the dom is not an element, "dom could not be serialized" will be output.
[in]	fmt	The printf-style format to log. If NULL, equivalent to "".
[in]	...	Extra parameters to interpolate into {fmt}.

JABBERWERX_API void JABBERWERX_API void jw_log_err	(	jw_loglevel	level,
		jw_err *	err,
		const char *	fmt,
			...
	)

Log an error, with extra information. If the error is NULL, just use the extra information.

Note: Not thread-safe with respect to the current log level.

Invariant: fmt != NULL

Parameters

[in]	level	The log level for this message. Note that JW_LOG_NONE is not a valid log level to pass to this function.
[in]	err	The error to be printed (if not NULL).
[in]	fmt	The printf-style format to log
[in]	...	Extra parameters to interpolate into {fmt}.

JABBERWERX_API jw_loglevel jw_log_get_level ( )

Get the current log level.

Return values

The	current log level.

JABBERWERX_API const char* jw_log_level_name ( jw_loglevel level )

Retrieve the string version of the jw_loglevel enum.

Parameters

level The log level to lookup

Return values

const char * The message for {level}

JABBERWERX_API int JABBERWERX_API void jw_log_pop_ndc ( int ndc_depth )

Pops a nested diagnostic context from the NDC stack.

Parameters

ndc_depth The value returned from jw_log_push_ndc(). If this value does not match the current NDC stack depth, a warning will be logged and the stack will be reduced to the expected depth. If 0 is passed in, this function is a noop.

JABBERWERX_API int jw_log_push_ndc	(	const char *	fmt,
			...
	)

Pushes a nested diagnostic context onto the NDC stack. The given message will be prefixed to all subsequent messages until a corresponding call to jw_log_pop_ndc() is made.

Invariant: fmt != NULL

Parameters

[in]	fmt	The printf-style format string
[in]	...	Extra parameters to interpolate into {fmt}.

Returns: The depth of the NDC stack after the given push. This must later be passed to jw_log_pop_ndc() to verify the consistency of the NDC stack. If this function fails to push (due, for example, to a low memory condition or a malformed format string), an appropriate warning will be printed and 0 will be returned.

JABBERWERX_API void jw_log_set_function ( jw_log_vararg_function fn )

Set the logging function.

Log function defaults to vfprintf. A null parameter resets the log function to its default.

Note: Not thread-safe.

Parameters

fn	The vfprintf-like function to use.

JABBERWERX_API void jw_log_set_level ( jw_loglevel level )

Set the current log level, defaults to JW_LOG_INFO.

Everything at this level or less verbose than this level will be printed.

Note: Not thread-safe.

Parameters

level The new log level.

JABBERWERX_API void jw_log_set_ndc_enabled ( bool enabled )

Enables or disables printing the NDC prefix for log messages. By default, the NDC prefix is enabled.

Parameters

[in] enabled true if the NDC should be output; otherwise false.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation