Logging Facility

Macros
#define	PJ_LOG(level, arg)

Typedefs
typedef void	pj_log_func(int level, const char *data, int len)

Enumerations
enum	pj_log_decoration {   PJ_LOG_HAS_DAY_NAME = 1 , PJ_LOG_HAS_YEAR = 2 , PJ_LOG_HAS_MONTH = 4 , PJ_LOG_HAS_DAY_OF_MON = 8 ,   PJ_LOG_HAS_TIME = 16 , PJ_LOG_HAS_MICRO_SEC = 32 , PJ_LOG_HAS_SENDER = 64 , PJ_LOG_HAS_NEWLINE = 128 ,   PJ_LOG_HAS_CR = 256 , PJ_LOG_HAS_SPACE = 512 , PJ_LOG_HAS_COLOR = 1024 , PJ_LOG_HAS_LEVEL_TEXT = 2048 ,   PJ_LOG_HAS_THREAD_ID = 4096 , PJ_LOG_HAS_THREAD_SWC = 8192 , PJ_LOG_HAS_INDENT =16384 }

Functions
void	pj_log_write (int level, const char *buffer, int len)
void	pj_log (const char *sender, int level, const char *format, va_list marker)
void	pj_log_set_log_func (pj_log_func *func)
pj_log_func *	pj_log_get_log_func (void)
void	pj_log_set_level (int level)
int	pj_log_get_level (void)
void	pj_log_set_decor (unsigned decor)
unsigned	pj_log_get_decor (void)
void	pj_log_add_indent (int indent)
void	pj_log_set_indent (int indent)
int	pj_log_get_indent (void)
void	pj_log_push_indent (void)
void	pj_log_pop_indent (void)
void	pj_log_set_color (int level, pj_color_t color)
pj_color_t	pj_log_get_color (int level)
pj_status_t	pj_log_init (void)

Detailed Description

The PJLIB logging facility is a configurable, flexible, and convenient way to write logging or trace information.

To write to the log, one uses construct like below:

  ...
  PJ_LOG(3, ("main.c", "Starting hello..."));
  ...
  PJ_LOG(3, ("main.c", "Hello world from process %d", pj_getpid()));
  ...

In the above example, the number 3 controls the verbosity level of the information (which means "information", by convention). The string "main.c" specifies the source or sender of the message.

Examples

For examples, see:

• Example: Log, Hello World.

Macro Definition Documentation

PJ_LOG

#define PJ_LOG	(		level,
			arg
	)

Write log message. This is the main macro used to write text to the logging backend.

Parameters

level	The logging verbosity level. Lower number indicates higher importance, with level zero indicates fatal error. Only numeral argument is permitted (e.g. not variable).
arg	Enclosed 'printf' like arguments, with the first argument is the sender, the second argument is format string and the following arguments are variable number of arguments suitable for the format string.

Sample:

PJ_LOG(2, (__FILE__, "current value is %d", value));

Typedef Documentation

pj_log_func

typedef void pj_log_func(int level, const char *data, int len)

Signature for function to be registered to the logging subsystem to write the actual log message to some output device.

Parameters

level	Log level.
data	Log message, which will be NULL terminated.
len	Message length.

Enumeration Type Documentation

pj_log_decoration

enum pj_log_decoration

Log decoration flag, to be specified with pj_log_set_decor().

Enumerator
PJ_LOG_HAS_DAY_NAME	Include day name [default: no]
PJ_LOG_HAS_YEAR	Include year digit [no]
PJ_LOG_HAS_MONTH	Include month [no]
PJ_LOG_HAS_DAY_OF_MON	Include day of month [no]
PJ_LOG_HAS_TIME	Include time [yes]
PJ_LOG_HAS_MICRO_SEC	Include microseconds [yes]
PJ_LOG_HAS_SENDER	Include sender in the log [yes]
PJ_LOG_HAS_NEWLINE	Terminate each call with newline [yes]
PJ_LOG_HAS_CR	Include carriage return [no]
PJ_LOG_HAS_SPACE	Include two spaces before log [yes]
PJ_LOG_HAS_COLOR	Colorize logs [yes on win32]
PJ_LOG_HAS_LEVEL_TEXT	Include level text string [no]
PJ_LOG_HAS_THREAD_ID	Include thread identification [no]
PJ_LOG_HAS_THREAD_SWC	Add mark when thread has switched [yes]
PJ_LOG_HAS_INDENT	Indentation. Say yes! [yes]

Function Documentation

pj_log()

void pj_log	(	const char *	sender,
		int	level,
		const char *	format,
		va_list	marker
	)

Write to log.

Parameters

sender	Source of the message.
level	Verbosity level.
format	Format.
marker	Marker.

pj_log_add_indent()

void pj_log_add_indent

(

int

indent

)

Add indentation to log message. Indentation will add PJ_LOG_INDENT_CHAR before the message, and is useful to show the depth of function calls.

Parameters

indent

The indentation to add or substract. Positive value adds current indent, negative value subtracts current indent.

pj_log_get_color()

pj_color_t pj_log_get_color

(

int

level

)

Get color of log messages.

Parameters

level

Log level which color will be returned.

Returns

Log color.

pj_log_get_decor()

unsigned pj_log_get_decor

(

void

)

Get current log decoration flag.

Returns

Log decoration flag.

pj_log_get_indent()

int pj_log_get_indent

(

void

)

Get current indentation value.

Returns

Current indentation value.

pj_log_get_level()

int pj_log_get_level

(

void

)

Get current maximum log verbositylevel.

Returns

Current log maximum level.

pj_log_get_log_func()

pj_log_func * pj_log_get_log_func

(

void

)

Get the current log output function that is used to write log messages.

Returns

Current log output function.

pj_log_init()

pj_status_t pj_log_init

(

void

)

Internal function to be called by pj_init()

pj_log_pop_indent()

void pj_log_pop_indent

(

void

)

Pop indentation (to the left) by default value (PJ_LOG_INDENT_SIZE).

pj_log_push_indent()

void pj_log_push_indent

(

void

)

Push indentation to the right by default value (PJ_LOG_INDENT_SIZE).

pj_log_set_color()

void pj_log_set_color	(	int	level,
		pj_color_t	color
	)

Set color of log messages.

Parameters

level	Log level which color will be changed.
color	Desired color.

pj_log_set_decor()

void pj_log_set_decor

(

unsigned

decor

)

Set log decoration. The log decoration flag controls what are printed to output device alongside the actual message. For example, application can specify that date/time information should be displayed with each log message.

Parameters

decor

Bitmask combination of pj_log_decoration to control the layout of the log message.

pj_log_set_indent()

void pj_log_set_indent

(

int

indent

)

Set indentation to specific value.

Parameters

indent

The indentation value.

pj_log_set_level()

void pj_log_set_level

(

int

level

)

Set maximum log level. Application can call this function to set the desired level of verbosity of the logging messages. The bigger the value, the more verbose the logging messages will be printed. However, the maximum level of verbosity can not exceed compile time value of PJ_LOG_MAX_LEVEL.

Parameters

level

The maximum level of verbosity of the logging messages (6=very detailed..1=error only, 0=disabled)

pj_log_set_log_func()

void pj_log_set_log_func

(

pj_log_func *

func

)

Change log output function. The front-end logging functions will call this function to write the actual message to the desired device. By default, the front-end functions use pj_log_write() to write the messages, unless it's changed by calling this function.

Parameters

func	The function that will be called to write the log messages to the desired device.

pj_log_write()

void pj_log_write	(	int	level,
		const char *	buffer,
		int	len
	)

Default logging writer function used by front end logger function. This function will print the log message to stdout only. Application normally should NOT need to call this function, but rather use the PJ_LOG macro.

Parameters

level	Log level.
buffer	Log message.
len	Message length.