DbgLog 


DbgLog - Advanced Debugging Messages Filter and Logger


Overview
--------

	The DbgLog library filters and logs debugging/error messages according
	to errno, calling module/function, warning keyword and debugging level.
	Particular errno/keyword can be made fatal. Output log files depend on
	keyword.

	Typical output looks like:
---------------------------------------------------------------------------------------
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

	But the output format can also be changed at will by setting a format
	string.

	This tool offers a tunable insight into the hierarchy of methods called
	within the libraries using it. It provides a way to trace and debug invalid
	data as well as misbehaving functions. The ability to turn off or filter
	whole segments of the debugging traces ensures that debugging will not be
	hindered by useless data. It filters output much in the same way as system
	calls debugging tools (such as strace) allow.


Programming interface
---------------------

	The API definition is entirely contained in the <DbgLog.h> include file.

	At the development stage, the main entry point in the API is the DbgLog
	funtion, that generates a log entry. To do that, this call must be supplied
	with contextual information, like function name, type of entry, and severity
	level. While this may seem cumbersome at first, this call needs only be used
	in error contexts, meaning its use is not too frequent.

        The synopsis of the variadic function DbgLog is:

#include <DbgLog.h>

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

	'mod' is the calling module or function name. This is the main context
	data, as this information will structure the actual hierarchy of calls.
	'key' is a debugging key, an identifier tag that will direct logging and
	filtering of this message. 'lev' is a numeric indication of severity
	(the lower, the more severe, with 0 having sense as "system-level error")


	At the degugging stage, several calls provide the tools to fine-tune the
        logging output: DbgLog_SetFormat, DbgLog_SetLogFd, DbgLog_UpDbgLvl and
        DbgLog_DnDbgLvl, DbgLog_AddFatal and DbgLog_DelFatal.
        It is also possible to set the active degugging levels with a simple
        .properties file, using the DbgCfg library (see the DbgCfg documentation).

	DbgLog_SetFormat has a single string argument, determining the format
	of log entries. The remaining functions have a debug key as first argument,
	standing for a particular class of filtering and, more generally, handling
	of that class of messages. The second argument is, for DbgLog_SetLogFd, an
	output file descriptor in which the messages will be written. The ...DbgLvl
	calls use a binary mask of levels (between 0 and 31) to set on or off. The
	...Fatal calls set or unset some system error values to trigger immediate
	termination.

	The [DbgLog_api documentation] offers a detailed description of the library's
	functions and symbols. 

Download
--------

	The latest version of DbgLog can be obtained at
	http://www.varkhan.net/software/DbgLog
	

Author
------

	Author		: Yann LANDRIN-SCHWEITZER, a.k.a. Varkhan
	Contact		: varkhan@varkhan.net
	Homepage	: http://www.varkhan.net/


License
-------

	This library is free software;  you can redistribute it and/or modify it
	under  the terms of the  GNU Lesser General Public License  as published
	by the  Free Software Foundation;  either version 2.1 of the License, or
	(at your option) any later version.


	This  library  is  distributed  in  the hope that it will be useful, but
	WITHOUT   ANY   WARRANTY;   without   even   the   implied  warranty  of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
	General Public License for more details.


	You should have received a copy of the GNU Lesser General Public License
	along with this library;  if not, write to the Free Software Foundation,
	Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA