DbgLog - Advanced Debugging Messages Filter and Logger

Description

DbgLog

errno

IPC.....	<04>	1016120237s\|706271us	[000004] :	0003	@	main	>	No such process	(0000000543)

dbg	dbg	time	msg	errno		module		errno message	opt args
keywd	level	seconds\|milisec	number

Programming Interface

DbgLog.h

Overview

DbgLog

#include <DbgLog.h>

void DbgLog(const char * mod, const char * key, unsigned char lev, const char * mes, ...) ;

mod

key

lev

DbgLog_SetFormat

DbgLog_SetLogFd

DbgLog_UpDbgLvl

DbgLog_DnDbgLvl

DbgLog_AddFatal

DbgLog_DelFatal

.properties

DbgCfg

DbgLog_SetFormat

DbgLog_SetLogFd

...DbgLvl

...Fatal

Output format control

Function DbgLog_SetFormat

void DbgLog_SetFormat(char * fmt) ;

Sets the format of output messages.

	Args:
		_ fmt	: format string

Note:
	The format string is printed as-is for each log entry, except for escape sequences
	of the form '%d?', where d desings an optionnal decimal number indicating the size
	of this field, and ? is a character indicating the field type. Here is a list of
	valid types, and their function:
	_ %	: a litteral '%' character
	_ k	: log key
	_ l	: log level
	_ s	: time of error (seconds component)
	_ u	: time of error (microseconds component)
	_ n	: entry number
	_ c	: calling function or module
	_ e	: error number (LibC errno)
	_ r	: error message related to the error number
	_ m	: user message
	The default format is '%8k<%2l> %10ss\|%6uus [%6n] : %4e @ %c > %r (%m)'.

Filters control

Function DbgLog_SetLogFd

void DbgLog_SetLogFd(char * key, int fd) ;

Sets log file descriptor.

Args:
	_ key	: filter key identifier
	_ fd	: file descriptor representing an open stream to use to print traces

	Note:
		If the key argument is the empty string, it designs the default (generic) filter,
		whose caracteristics are used as a basis for new filters, or when filter is unspecified.
		When the key is NULL, it designs ALL filters except the default.

Function DbgLog_DbgLvl

unsigned long DbgLog_DbgLvl(char * key) ;

Gets the state of debugging levels.

	Args:
		_ key	: filter key identifier

Returns:
	_ 0	: if key was NULL, or did not refer to an existing filter
	else the current mask of active debugging levels.

	Note:
		If the key argument is the empty string, it designs the default (generic) filter,
		whose caracteristics are used as a basis for new filters, or when filter is unspecified.
		When the key is NULL, it designs ALL filters except the default.
		The levels mask set bits positions (as in '<<') design debugging levels set ON.

Function DbgLog_UpDbgLvl

void DbgLog_UpDbgLvl(char * key, unsigned long lev) ;

Sets debugging levels ON.

Args:
	_ key	: filter key identifier
	_ lev	: debugging levels mask

	Note:
		If the key argument is the empty string, it designs the default (generic) filter,
		whose caracteristics are used as a basis for new filters, or when filter is unspecified.
		When the key is NULL, it designs ALL filters except the default.
		The levels mask set bits positions (as in '<<') design debugging levels set ON.

Function DbgLog_DnDbgLvl

void DbgLog_DnDbgLvl(char * key, unsigned long lev) ;

Sets debugging levels OFF.

Args:
	_ key	: filter key identifier
	_ lev	: debugging levels mask

	Note:
		If the key argument is the empty string, it designs the default (generic) filter,
		whose caracteristics are used as a basis for new filters, or when filter is unspecified.
		When the key is NULL, it designs ALL filters except the default.
		The levels mask set bits positions (as in '<<') design debugging levels set OFF.

Function DbgLog_AddFatal

void DbgLog_AddFatal(char * key, int err) ;

Adds a fatal errno.

Args:
	_ key	: filter key identifier
	_ err	: concerned errno

	Note:
		If the key argument is the empty string, it designs the default (generic) filter,
		whose caracteristics are used as a basis for new filters, or when filter is unspecified.
		When the key is NULL, it designs ALL filters except the default.
		When an error with this filter key AND this errno is encountered, this triggers
		immediate termination (after the printing of a log entry), through _exit (2).

Function DbgLog_DelFatal

void DbgLog_DelFatal(char * key, int err) ;

Deletes a fatal errno.

Args:
	_ key	: filter key identifier
	_ err	: concerned errno

	Note:
		If the key argument is the empty string, it designs the default (generic) filter,
		whose caracteristics are used as a basis for new filters, or when filter is unspecified.
		When the key is NULL, it designs ALL filters except the default.

Log entries

Function DbgLog

void DbgLog(const char * mod, const char * key, unsigned char lev, const char * mes, ...) ;

Produces an error from module/function 'mod', filter key 'key' and message 'mes', at debugging level 'lev'.

Args:
	_ mod	: name of the function/module from which this call was issued
	_ key	: key of filter to be used
	_ lev	: debugging level at which this error is raised
	_ mes	: optional message to add to transcript
	_ ...	: arguments to be formatted in the mes string

Note:
	Use a NULL value for mes when no message needs to be printed.
	Variable arguments are formatted following escapes in the message string,
	taking the form '%d?' where d is any number of digits and ? is either:
	_ %	: a litteral '%' character is printed
	_ c	: the argument is a character
	_ s	: the argument is a string, and will be printed as-is
	_ d	: the argument is a signed number, printed in decimal form
	_ u	: the argument is an unsigned number, printed in decimal form
	_ x	: the argument is an unsigned number, printed in hexadecimal form
	For s,u,x, the digits before the conversion character give the maximum
	number of characters to be printed.

Function DbgLog_

void DbgLog_(const char * mod, const char * key, unsigned char lev, const char * mes, va_list ap) ;

Produces an error from module/function 'mod', filter key 'key' and message 'mes', at debugging level 'lev'.

Args:
	_ mod	: name of the function/module from which this call was issued
	_ key	: key of filter to be used
	_ lev	: debugging level at which this error is raised
	_ mes	: optional message to add to transcript
	_ ap	: optional variable arguments list

Note:
	Use a NULL value for mes when no message needs to be printed.
	Variable arguments are formatted following escapes in the message string,
	taking the form '%d?' where d is any number of digits and ? is either:
	_ %	: a litteral '%' character is printed
	_ c	: the argument is a character
	_ s	: the argument is a string, and will be printed as-is
	_ d	: the argument is a signed number, printed in decimal form
	_ u	: the argument is an unsigned number, printed in decimal form
	_ x	: the argument is an unsigned number, printed in hexadecimal form
	For s,u,x, the digits before the conversion character give the maximum
	number of characters to be printed.
	This function does not call va_start (of course) and va_end, so the value of
	ap is undefined after the call, and va_end must be called by the application.

Block-wise logging

Function DbgLog_OpenBlock

void DbgLog_OpenBlock(void) ;

Starts a new debugging block.

Function DbgLog_CloseBlock

void DbgLog_CloseBlock(void) ;

Closes the current debugging block, reactivating the last one.

Function DbgLog_Flush

void DbgLog_Flush(void) ;

Prints the last debugging block in log.

Download

The latest version of DbgLog can be obtained from

http://www.varkhan.net/software/DbgLog

Author

Name:		Yann LANDRIN-SCHWEITZER aka Varkhan

Mail:		varkhan at varkhan dot net

Home:		http://www.varkhan.net/

License