SYSLOG


Used for a common point to control program logging. On the fly, the target for any logging messages may be changed. Options also include time stamp on all messages either in delta or absolute format. Resolution of times can be from CPU ticks to seconds. Debug mode code generates messages which include __FILE__(__LINE__): prefixes by default.

By default logging is only generated when using a debug target (debug, static_debug). When building a release target, unless otherwise specified, all logging will be omitted. You can define DO_LOGGING before including logging.h which will force logging to be done regardless of the mode. Also, NO_LOGGING may be defined which will force logging to not be done regardless of the mode.

// example to force logging
#define DO_LOGGING
#include <logging.h>
// example to disable logging
#define NO_LOGGING
#include <logging.h>
// example to use logging in default mode
#include <logging.h>

Include

#include <logging.h>

Library

syslog

Required Libraries

(none)

Project Location

src/sysloglib

Defines

these symbols are actually defined in <types.h> which is bound to conflict at some point, and will have to be renamed. In debug mode - the following symbols are defined as...

SymbolEquates toUsed when...
DBG_SRC, __FILE__, __LINE__passing 'here' to a routine expecting DBG_PASS (after 1 or more paramters)
DBG_LEADSRC__FILE__, __LINE__, passing 'here' to a routine expecting DBG_LEADPASS (before 1 or more paramters)
DBG_VOIDSRC__FILE__, __LINE__passing 'here' to a routine expecting DBG_VOIDPASS when otherwise the function has no (void) paramters.
DBG_PASS, CTEXTSTR pFile, uint32_t nLineDefining that a routine accepts a 'here' from the caller after 1 or more paramters.
DBG_LEADPASSCTEXTSTR pFile, uint32_t nLine, Defining that a routine accepts a 'here' from the caller before 1 or more paramters.
DBG_VOIDPASSCTEXTSTR pFile, uint32_t nLineDefining that a routine accepts a 'here' from the caller when otherwise no (void) paramters are used.
DBG_RELAY, pFile, nLineUsed to foward information passed in to a DBG_PASS to a routine expecting DBG_PASS (after 1 or more parameters)
DBG_LEADRELAYpFile, nLine, Used to foward information passed in to a DBG_LEADPASS to a routine expecting DBG_LEADPASS (before 1 or more parameters)
DBG_VOIDRELAYpFile, nLineUsed to foward information passed in to a DBG_VOIDPASS to a routine expecting DBG_VOIDPASS to a function otherwise expecing no (void) paramters.
DBG_FILELINEFMT"%s(%ld): "Used to define optional paramter to a printf type format routine.

In release mode - the following symbols are defined as...

SymbolEquates toUsed when...
DBG_SRC[nothing]passing 'here' to a routine expecting DBG_PASS (after 1 or more paramters)
DBG_LEADSRC[nothing]passing 'here' to a routine expecting DBG_LEADPASS (before 1 or more paramters)
DBG_VOIDSRC[nothing]passing 'here' to a routine expecting DBG_VOIDPASS when otherwise the function has no (void) paramters.
DBG_PASS[nothing]Defining that a routine accepts a 'here' from the caller after 1 or more paramters.
DBG_LEADPASS[nothing]Defining that a routine accepts a 'here' from the caller before 1 or more paramters.
DBG_VOIDPASSvoidDefining that a routine accepts a 'here' from the caller when otherwise no (void) paramters are used.
DBG_RELAY[nothing]Used to foward information passed in to a DBG_PASS to a routine expecting DBG_PASS (after 1 or more parameters)
DBG_LEADRELAY[nothing]Used to foward information passed in to a DBG_LEADPASS to a routine expecting DBG_LEADPASS (before 1 or more parameters)
DBG_VOIDRELAY[nothing]Used to foward information passed in to a DBG_VOIDPASS to a routine expecting DBG_VOIDPASS to a function otherwise expecing no (void) paramters.
DBG_FILELINEFMT[nothing]Used to define optional paramter to a printf type format routine.
Some things to note - when using these, leading and trailing commas are NOT written in the code which uses the define, this allows the comma to come and go depending on the mode compiled... It is preferred to use the trailing functions and NOT the LEAD functions. Assuming (and apparently this has become a BIG assumption) that a standard C stack frame is used, this allows debug mode code to use release mode libraries. A standard C stack assumes that the last parameters are passed onto the stack first. Therefore, if the release libraries are not expecting to have the extra parameters whether they are present because of the debug mode program or not does not matter. However, If the paramters are placed first, then there is NO interoperability between release and debug code.

Some examples of usage...

void function( DBG_VOIDPASS )
{
   printf( DBG_FILELINEFMT "This line marked %d times" DBG_PASS, i );
   printf( DBG_FILELINEFMT "called this..." DBG_RELAY );
}
void another( int a, int b DBG_PASS )
{
   function( DBG_VOIDRELAY );
}
void prefixed( DBG_LEADPASS int a, int b )
{
   another( a, b DBG_PASS );
   another( a, b DBG_SRC );
}

//becomes in debug mode...
void function( CTEXTSTR pFile, uint32_t nLine )
{
   printf( "%s(%ld): This line marked %d times", __FILE__, __LINE__, i );
   printf( "%s(%ld): called this...", pFile, nLine );
}
void another( int a, int b , CTEXTSTR pFile, uint32_t nLine )
{
   function( pFile, nLine );
}
void prefixed( CTEXTSTR pFile, uint32_t nLine, int a, int b )
{
   another( a, b, pFile, nLine );
   another( a, b, __FILE__, __LINE__ );
}

//becomes in release mode...
void function( void )
{
   printf( "This line marked %d times", i );
   printf( "called this..." );
}
void another( int a, int b )
{
   function( );
}
void prefixed( int a, int b )
{
   another( a, b );
   another( a, b );
}

Routines

void SetSystemLog( int type, ... )

Set the current target of logging. The library itself, if unspecified defaults to SYSLOG_NONE in all modes. The 'type' parameter is one of the following values.
SYSLOG_NONEDisables any logging output anywhere.
SYSLOG_FILEOptional parameter is a FILE* indicating a previously opened file. stdout, stderr are good examples of this.
SYSLOG_FILENAMEOptional paramter is a char* which is the name of a file to open using fopen("wt").
SYSLOG_UDPLogging is generated to localhost:514.
SYSLOG_UDPBROADCASTLogging is generated to 255.255.255.255:514

void lprintf(format,...)

This generates a logging message using vsnprintf internally. The buffer it writes into dynamically expands to meet any space requirement. Standard printf type formatting applies. A final newline is NOT required or desired, after every message a newline is forced. Since every message automatically gets a newline, the log would be double spaced if you put a new in the format. GCC supports this all by itself. Other compilers use PPC (Panther's Preproccesor for C) to preprocess .c files into .i files, which are then passed to the compiler.

void Log(char *string)
void Log1(char *format,param1)
....
void Log10(format,param1, ..., param10)

Before __VA_ARGS__ was well supported logging had to have an exact count of paramters. These macros still exist, any LogX value between 1 and 10 may be used, in which case the first paramter is a format string. Log() alone passes the string as a literal, and no format operations are done on it. This method may still be used for supporting systems which cannot run PPC or are not using GCC.

void SystemLog( char* )
void SystemLogEx( char* DBG_PASS )

This behaves much like Log(), and passes a literal string to be logged. The ...Ex version maybe be used to pass some other file/line information other than the default 'here'.