Logging Facility

This section contains logging specific APIs. More...

Macros
#define	RU_LOG_NONE   0
	This level disables logging altogether. More...
#define	RU_LOG_CRIT   1
	This level reduces logging to fatal errors and generally unexpected serious stuff. More...
#define	RU_LOG_WARN   2
	This level includes RU_LOG_CRIT and general warning messages. More...
#define	RU_LOG_INFO   3
	This level includes RU_LOG_WARN and general information. Usual low quantity. More...
#define	RU_LOG_VERB   4
	This level includes RU_LOG_INFO and verbose logging used for debugging and is usually high quantity. More...
#define	RU_LOG_DBUG   5
	This level includes RU_LOG_VERB and is a debugging logging level used for debugging things that are normally assumed to be working. It is usually off because it litters the logs with often redundant data. More...
#define	ruCritLog(msg)   ruLog_(RU_LOG_CRIT, "%s", msg)
	Emits a CRIT level log message. More...
#define	ruCritLogf(fmt, ...)   ruLog_(RU_LOG_CRIT, fmt, __VA_ARGS__)
	Emits a CRIT level log message. More...
#define	ruWarnLog(msg)   ruLog_(RU_LOG_WARN, "%s", msg)
	Emits a WARN level log message. More...
#define	ruWarnLogf(fmt, ...)   ruLog_(RU_LOG_WARN, fmt, __VA_ARGS__)
	Emits a WARN level log message. More...
#define	ruInfoLog(msg)   ruLog_(RU_LOG_INFO, "%s", msg)
	Emits a INFO level log message. More...
#define	ruInfoLogf(fmt, ...)   ruLog_(RU_LOG_INFO, fmt, __VA_ARGS__)
	Emits a INFO level log message. More...
#define	ruVerbLog(msg)   ruLog_(RU_LOG_VERB, "%s", msg)
	Emits a VERB level log message. More...
#define	ruVerbLogf(fmt, ...)   ruLog_(RU_LOG_VERB, fmt, __VA_ARGS__)
	Emits a VERB level log message. More...
#define	ruDbgLog(msg)   ruLog_(RU_LOG_DBUG, "%s", msg)
	Emits a DBUG level log message. More...
#define	ruDbgLogf(fmt, ...)   ruLog_(RU_LOG_DBUG, fmt, __VA_ARGS__)
	Emits a DBUG level log message. More...
#define	ruDump8(msg, start)
	Debug logs the 8 bytes following start preceded by given message. More...
#define	ruDump16(msg, start)
	Debug logs the 16 bytes following start preceded by given message. More...

Typedefs
typedef void(*	ruLogFunc) (perm_ptr userData, uint32_t logLevel, trans_chars msg)
	The type of function to pass to ruSetLogger in order to hook up logging. More...
typedef void(*	ruCloseFunc) (perm_ptr userData)
	The type of function to pass to ruSinkCtxNew which will be called when ruFileLogSink has closed its logfile. More...
typedef int(*	ruWriteFunc) (trans_chars buf, FILE *wh)
	The type of function to pass to ruSinkWriteCb to substitute fputs. More...
typedef ptr	ruPreCtx
	Opaque pointer to ruPreLogSink object. More...
typedef ptr	ruSinkCtx
	Opaque pointer to ruFileLogSink object. More...

Functions
RUAPI ruPreCtx	ruPreCtxNew (void)
	Creates a new pre logging context for use with ruPreLogSink. More...
RUAPI ruPreCtx	ruPreCtxFree (ruPreCtx rpc, bool flush)
	Frees the given ruPreCtx. More...
RUAPI void	ruPreLogSink (perm_ptr rpc, uint32_t logLevel, trans_chars msg)
	Pre logging sink to store log entries until a final log sink has been established. More...
RUAPI ruSinkCtx	ruSinkCtxNew (trans_chars filePath, ruCloseFunc closeCb, perm_ptr closeCtx)
	Creates a new context to use with ruFileLogSink. More...
RUAPI int32_t	ruSinkWriteCb (ruSinkCtx rsc, ruWriteFunc writeCb)
	Allow substituting fputs call with custom implementation. More...
RUAPI int32_t	ruSinkCtxPath (ruSinkCtx rsc, trans_chars filePath)
	Allows changing the file path of the given ruSinkCtx. More...
RUAPI ruSinkCtx	ruSinkCtxFree (ruSinkCtx rsc)
	Frees the given ruSinkCtx after ruStopLogger has been called. This must not be called when the context is still in use. More...
RUAPI void	ruFileLogSink (perm_ptr rsc, uint32_t logLevel, trans_chars msg)
	A log sink that logs into the filepath set in the given ruSinkCtx. More...
RUAPI void	ruStdErrLogSink (perm_ptr udata, uint32_t logLevel, trans_chars msg)
	A convenience logging implementation that logs to stderr. More...
RUAPI ruCleaner	ruGetCleaner (void)
	Public ruCleaner instance that is used by the logger when cleaning is enabled. More...
RUAPI perm_ptr	ruGetLogCtx (void)
	Returns the ruSetLogger userData in use by the current logger. More...
RUAPI void	ruSetLogger (ruLogFunc logger, uint32_t logLevel, perm_ptr userData, bool cleaned, bool threaded)
	Sets the global logging function for this process. More...
RUAPI void	ruLoggerUnblock (void)
	Unblocks any thread blocked on logging by removing the size limit of the log queue. More...
RUAPI void	ruStopLogger (void)
	Stop the current logger and flush the queue before returning. More...
RUAPI void	ruSetLogLevel (uint32_t logLevel)
	Adjusts the current log level. More...
RUAPI uint32_t	ruGetLogLevel (void)
	Returns the currently set log level. More...
RUAPI bool	ruDoesLog (uint32_t log_level)
	Returns whether the given log level should log. More...
RUAPI void	ruLogDbg (trans_chars filePath, trans_chars func, int32_t line, trans_chars format,...)
	Prints given parameters to stdout. More...
RUAPI void	ruDoLog (uint32_t log_level, trans_chars filePath, trans_chars func, int32_t line, trans_chars format,...)
	Logs the given parameters if logging is set. More...
RUAPI void	ruDoLogV (uint32_t log_level, trans_chars filePath, trans_chars func, int32_t line, trans_chars format, va_list args)
	Logs the given parameters if logging is set. More...
RUAPI alloc_chars	ruMakeLogMsgV (uint32_t log_level, trans_chars filePath, trans_chars func, int32_t line, trans_chars format, va_list args)
RUAPI void	ruRawLog (uint32_t log_level, trans_chars msg)
	Sends the given message as is to the current log sink. More...
RUAPI void	ruFlushLog (void)
	Sends a NULL message with log level RU_LOG_CRIT to the current log sink, usually causing it to flush or close the log file. More...
RUAPI void	ruLastLog (void)
	Sends a NULL message with log level RU_LOG_NONE to the current log sink, usually causing it to close the log file and call a potential close callback. More...
RUAPI char *	ruMakeLogMsg (uint32_t log_level, trans_chars file, trans_chars func, int32_t line, trans_chars format,...)

Detailed Description

This section contains logging specific APIs.

Example:

#include <regify-util.h>
 
void testlog(trans_chars logPath, bool cleaning, bool threaded) {
    ruSinkCtx sc = NULL;
    // Use the pre logger until we determine where to log to...
    ruPreCtx pc = ruPreCtxNew();
    ruSetLogger(ruPreLogSink, RU_LOG_DBUG, pc, cleaning, threaded);
 
    if (cleaning) {
        ruInfoLog("Using log cleaner");
        ruCleanAdd(ruGetCleaner(), "testsecret", "^^^TEST_SECRET^^^");
        ruVerbLog("keeping testsecret hidden");
    }
    if (ruStrEmpty(logfile)) {
        ruInfoLog("Using std error logger");
        ruSetLogger(ruStdErrLogSink, RU_LOG_DBUG, NULL, cleaning, threaded);
    } else {
        ruInfoLogf("Logging to '%s'", logfile);
        sc = ruSinkCtxNew(logfile, NULL, NULL);
        ruSetLogger(ruFileLogSink, RU_LOG_DBUG, sc, cleaning, threaded);
    }
    // flush and free the pre logger
    pc = ruPreCtxFree(pc, true);
 
    // program logic here...
    ruInfoLog("starting with testsecret and cleaner");
 
    // clean up when finished
    ruInfoLog("stopping logger");
    ruStopLogger();
    ruSinkCtxFree(sc);
}

Macro Definition Documentation

RU_LOG_CRIT

#define RU_LOG_CRIT   1

This level reduces logging to fatal errors and generally unexpected serious stuff.

This level is also used in conjunction with a NULL log message to prompt the log sink to flush and close the log file. This is done using ruFlushLog.

RU_LOG_DBUG

#define RU_LOG_DBUG   5

This level includes RU_LOG_VERB and is a debugging logging level used for debugging things that are normally assumed to be working. It is usually off because it litters the logs with often redundant data.

RU_LOG_INFO

#define RU_LOG_INFO   3

This level includes RU_LOG_WARN and general information. Usual low quantity.

RU_LOG_NONE

#define RU_LOG_NONE   0

This level disables logging altogether.

This level is also used in conjunction with a NULL log message to prompt the log sink to flush and close the log file and call a potential close callback. If the logger is threaded it will also cause the thread to terminate. This is done using ruLastLog.

RU_LOG_VERB

#define RU_LOG_VERB   4

This level includes RU_LOG_INFO and verbose logging used for debugging and is usually high quantity.

RU_LOG_WARN

#define RU_LOG_WARN   2

This level includes RU_LOG_CRIT and general warning messages.

ruCritLog

#define ruCritLog

(

msg

)

ruLog_(RU_LOG_CRIT, "%s", msg)

Emits a CRIT level log message.

Parameters

msg	The message to be logged.

ruCritLogf

#define ruCritLogf	(		fmt,
			...
	)		ruLog_(RU_LOG_CRIT, fmt, __VA_ARGS__)

Emits a CRIT level log message.

Parameters

fmt	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

ruDbgLog

#define ruDbgLog

(

msg

)

ruLog_(RU_LOG_DBUG, "%s", msg)

Emits a DBUG level log message.

Parameters

msg	The message to be logged.

ruDbgLogf

#define ruDbgLogf	(		fmt,
			...
	)		ruLog_(RU_LOG_DBUG, fmt, __VA_ARGS__)

Emits a DBUG level log message.

Parameters

fmt	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

ruDump16

#define ruDump16	(		msg,
			start
	)

Value:

    ruDbgLogf("%s @0x%x %02x %02x %02x %02x  %02x %02x %02x %02x  %02x %02x %02x %02x  %02x %02x %02x %02x", msg, (start), \
        (uint8_t)*(start), (uint8_t)*((start)+1), (uint8_t)*((start)+2), (uint8_t)*((start)+3), \
        (uint8_t)*((start)+4), (uint8_t)*((start)+5), (uint8_t)*((start)+6), (uint8_t)*((start)+7), \
        (uint8_t)*((start)+8), (uint8_t)*((start)+9), (uint8_t)*((start)+10), (uint8_t)*((start)+11), \
        (uint8_t)*((start)+12), (uint8_t)*((start)+13), (uint8_t)*((start)+14), (uint8_t)*((start)+15))

Debug logs the 16 bytes following start preceded by given message.

Parameters

msg	prefix message
start	address from where to start dumping bytes

ruDump8

#define ruDump8	(		msg,
			start
	)

Value:

    ruDbgLogf("%s @0x%x %02x %02x %02x %02x  %02x %02x %02x %02x", msg, (start), \
        (uint8_t)*(start), (uint8_t)*((start)+1), (uint8_t)*((start)+2), (uint8_t)*((start)+3), \
        (uint8_t)*((start)+4), (uint8_t)*((start)+5), (uint8_t)*((start)+6), (uint8_t)*((start)+7))

Debug logs the 8 bytes following start preceded by given message.

Parameters

msg	prefix message
start	address from where to start dumping bytes

ruInfoLog

#define ruInfoLog

(

msg

)

ruLog_(RU_LOG_INFO, "%s", msg)

Emits a INFO level log message.

Parameters

msg	The message to be logged.

ruInfoLogf

#define ruInfoLogf	(		fmt,
			...
	)		ruLog_(RU_LOG_INFO, fmt, __VA_ARGS__)

Emits a INFO level log message.

Parameters

fmt	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

ruVerbLog

#define ruVerbLog

(

msg

)

ruLog_(RU_LOG_VERB, "%s", msg)

Emits a VERB level log message.

Parameters

msg	The message to be logged.

ruVerbLogf

#define ruVerbLogf	(		fmt,
			...
	)		ruLog_(RU_LOG_VERB, fmt, __VA_ARGS__)

Emits a VERB level log message.

Parameters

fmt	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

ruWarnLog

#define ruWarnLog

(

msg

)

ruLog_(RU_LOG_WARN, "%s", msg)

Emits a WARN level log message.

Parameters

msg	The message to be logged.

ruWarnLogf

#define ruWarnLogf	(		fmt,
			...
	)		ruLog_(RU_LOG_WARN, fmt, __VA_ARGS__)

Emits a WARN level log message.

Parameters

fmt	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

Typedef Documentation

ruCloseFunc

typedef void(* ruCloseFunc) (perm_ptr userData)

The type of function to pass to ruSinkCtxNew which will be called when ruFileLogSink has closed its logfile.

Parameters

userData

The closeCtx reference that was passed to ruSinkCtxNew.

ruLogFunc

typedef void(* ruLogFunc) (perm_ptr userData, uint32_t logLevel, trans_chars msg)

The type of function to pass to ruSetLogger in order to hook up logging.

When this function receives NULL for msg, it means that this may be the last log call this function will receive in the current context. This is intended to finalize whatever resources it may have, or simply to flush data.

Parameters

userData	The userData reference that was passed to ruSetLogger.
logLevel	Log level pertaining to this message. Log filtering has been done at this point, and this is to facilitate further log level based processing decisions.
msg	The message to log, or NULL for flushing or closing.

ruPreCtx

typedef ptr ruPreCtx

Opaque pointer to ruPreLogSink object.

ruSinkCtx

typedef ptr ruSinkCtx

Opaque pointer to ruFileLogSink object.

ruWriteFunc

typedef int(* ruWriteFunc) (trans_chars buf, FILE *wh)

The type of function to pass to ruSinkWriteCb to substitute fputs.

Function Documentation

ruDoesLog()

RUAPI bool ruDoesLog

(

uint32_t

log_level

)

Returns whether the given log level should log.

This function considers the set log level only if a logging function was set. If no logging function was set it will return false.

Parameters

log_level

Level to be considered.

Returns

Whether to log.

ruDoLog()

RUAPI void ruDoLog	(	uint32_t	log_level,
		trans_chars	filePath,
		trans_chars	func,
		int32_t	line,
		trans_chars	format,
			...
	)

Logs the given parameters if logging is set.

This function is really internal and used by the log macros.

Parameters

log_level	Log level of this message.
filePath	The source file where this message originates from.
func	The function that created this log entry.
line	The line where the log was created at.
format	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

ruDoLogV()

RUAPI void ruDoLogV	(	uint32_t	log_level,
		trans_chars	filePath,
		trans_chars	func,
		int32_t	line,
		trans_chars	format,
		va_list	args
	)

Logs the given parameters if logging is set.

This function is advanced and designed to be used by custom log macros.

Parameters

log_level	Log level of this message.
filePath	The source file where this message originates from.
func	The function that created this log entry.
line	The line where the log was created at.
format	The format specifier for the remaining arguments.
args	variable argument list

ruFileLogSink()

RUAPI void ruFileLogSink	(	perm_ptr	rsc,
		uint32_t	logLevel,
		trans_chars	msg
	)

A log sink that logs into the filepath set in the given ruSinkCtx.

This sink checks its underlying file every 3 seconds to see whether it has moved or the ruSinkCtx filePath has changed. When it does, it closes its current file handle and reopens it to allow for logrotation to work. When it receives a NULL message, like through ruFlushLog, it closes its file. Through the use of ruSinkCtxPath, output files can be changed on the fly. Every time ruLastLog is called, it closes its log file and calls the ruSinkCtx closeCb if set.

Parameters

rsc	User data. Must be a ruSinkCtx.
logLevel	Ignored log level pertaining to this message.
msg	The message to log. NULL will cause it to close the log file.

ruFlushLog()

RUAPI void ruFlushLog

(

void

)

Sends a NULL message with log level RU_LOG_CRIT to the current log sink, usually causing it to flush or close the log file.

This call will block until a NULL has been sent to the given log sink.

ruGetCleaner()

RUAPI ruCleaner ruGetCleaner

(

void

)

Public ruCleaner instance that is used by the logger when cleaning is enabled.

Returns

Public ruCleaner singleton.

ruGetLogCtx()

RUAPI perm_ptr ruGetLogCtx

(

void

)

Returns the ruSetLogger userData in use by the current logger.

This is useful to determine whether it is safe to delete a ruSinkCtx without stopping a potentially otherwise used logger.

Returns

Current logger userdata.

ruGetLogLevel()

RUAPI uint32_t ruGetLogLevel

(

void

)

Returns the currently set log level.

Returns

The currently set log level.

ruLastLog()

RUAPI void ruLastLog

(

void

)

Sends a NULL message with log level RU_LOG_NONE to the current log sink, usually causing it to close the log file and call a potential close callback.

This call will block until a NULL has been sent to the given log sink.

ruLogDbg()

RUAPI void ruLogDbg	(	trans_chars	filePath,
		trans_chars	func,
		int32_t	line,
		trans_chars	format,
			...
	)

Prints given parameters to stdout.

This function is primarily intended to debug logging itself by compiling its usage in or out.

Example:

// logger debugging
#define LOGDBG 01
 
#if LOGDBG
#define logDbg(fmt, ...) ruLogDbg(__FILE__, __func__, __LINE__, fmt, __VA_ARGS__)
#else
#define logDbg(fmt, ...)
#endif
 
logDbg("%s", "a parameterless log statement");

Parameters

filePath	The source file where this message originates from.
func	The function that created this log entry.
line	The line where the log was created at.
format	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

ruLoggerUnblock()

RUAPI void ruLoggerUnblock

(

void

)

Unblocks any thread blocked on logging by removing the size limit of the log queue.

This is used when shutting down the logger to unblock pending entries and their associated threads.

ruMakeLogMsg()

RUAPI char* ruMakeLogMsg	(	uint32_t	log_level,
		trans_chars	file,
		trans_chars	func,
		int32_t	line,
		trans_chars	format,
			...
	)

Internal logging function used by the log macros.

Parameters

log_level	Log level of this message.
file	The source file where this message originates from.
func	The function that created this log entry.
line	The line where the log was created at.
format	The format specifier for the remaining arguments.
...	The remaining arguments that make up the log message.

Returns

The allocated log message to be freed by the caller after usage.

ruMakeLogMsgV()

RUAPI alloc_chars ruMakeLogMsgV	(	uint32_t	log_level,
		trans_chars	filePath,
		trans_chars	func,
		int32_t	line,
		trans_chars	format,
		va_list	args
	)

Internal logging function used by the log macros.

Parameters

log_level	Log level of this message.
filePath	The source file where this message originates from.
func	The function that created this log entry.
line	The line where the log was created at.
format	The format specifier for the remaining arguments.
args	variable argument list

Returns

The allocated log message to be freed by the caller after usage.

ruPreCtxFree()

RUAPI ruPreCtx ruPreCtxFree	(	ruPreCtx	rpc,
		bool	flush
	)

Frees the given ruPreCtx.

Parameters

rpc	context to free
flush	log the accumulated entries before freeing them.

Returns

NULL

ruPreCtxNew()

RUAPI ruPreCtx ruPreCtxNew

(

void

)

Creates a new pre logging context for use with ruPreLogSink.

This context is useful for temporarily storing log entries until the final log sink has been established. At that point this context may be freed optionally logging its content into the current logsink.

Returns

ruPreCtx object

ruPreLogSink()

RUAPI void ruPreLogSink	(	perm_ptr	rpc,
		uint32_t	logLevel,
		trans_chars	msg
	)

Pre logging sink to store log entries until a final log sink has been established.

When calling ruSetLogger with this sink, the log level should be set to RU_LOG_DBUG so that all potential entries will be accumulated. The actual filtering is done when this context is flushed. At that point entries will be filtered by the then current log level.

Parameters

rpc	User data. Must be a ruPreCtx.
logLevel	Log level pertaining to this message. Will be stored for flush time.
msg	The message to log. NULL will be ignored.

ruRawLog()

RUAPI void ruRawLog	(	uint32_t	log_level,
		trans_chars	msg
	)

Sends the given message as is to the current log sink.

Parameters

log_level	Log level of this message used solely for filtering.
msg	string to be logged without modification. The trailing line feed must be given.

ruSetLogger()

RUAPI void ruSetLogger	(	ruLogFunc	logger,
		uint32_t	logLevel,
		perm_ptr	userData,
		bool	cleaned,
		bool	threaded
	)

Sets the global logging function for this process.

When threaded is set, the log thread always follows up with one NULL message when there are no more messages to log. This is intended to facilitate log flushing. In the absense of the log thread this can also be accomplished by calling ruFlushLog. At the end ruStopLogger should be called to flush and close the log file. This function will block until the old logger has been stopped. If it used ruFileLogSink then the log will also have been flushed and closed before this function returns.

Parameters

logger	Logging function that will be called with messages.
logLevel	Loglevel to determine what gets logged.
userData	Opaque custom user data that will be passed to the ruLogFunc implementation.
cleaned	Whether to do real time password cleaning. Use the ruGetCleaner instance to add secrets to mask.
threaded	Whether to receive all logger calls from a dedicated thread. This is useful when many threads do lots of logging. This currently uses a bound ruList a la ruListNewBound with a size limit of 100000 entries. Call ruLoggerUnblock to prevent a slow logger from impeding process termination.

ruSetLogLevel()

RUAPI void ruSetLogLevel

(

uint32_t

logLevel

)

Adjusts the current log level.

Parameters

logLevel

New log level to log at.

ruSinkCtxFree()

RUAPI ruSinkCtx ruSinkCtxFree

(

ruSinkCtx

rsc

)

Frees the given ruSinkCtx after ruStopLogger has been called. This must not be called when the context is still in use.

Parameters

rsc	ruSinkCtx to free.

Returns

NULL

ruSinkCtxNew()

RUAPI ruSinkCtx ruSinkCtxNew	(	trans_chars	filePath,
		ruCloseFunc	closeCb,
		perm_ptr	closeCtx
	)

Creates a new context to use with ruFileLogSink.

Parameters

filePath	Path to where log file will be written. Directory must be writable.
closeCb	Optional callback to run when the old file has been closed after ruSinkCtxPath was called.
closeCtx	Optional context which will be passed to closeCb

Returns

New ruSinkCtx to free with ruSinkCtxFree.

ruSinkCtxPath()

RUAPI int32_t ruSinkCtxPath	(	ruSinkCtx	rsc,
		trans_chars	filePath
	)

Allows changing the file path of the given ruSinkCtx.

This will have immediate effect on logs sent to ruFileLogSink. When the old log has been closed the closeCb function given to ruSinkCtxNew will be called exactly one time. In either case this function will block until the old file has been closed. None of this will happen if the new filePath is equal to the old filePath.

Parameters

rsc	ruSinkCtx to update.
filePath	Path to new log file.

Returns

Status of the operation.

ruSinkWriteCb()

RUAPI int32_t ruSinkWriteCb	(	ruSinkCtx	rsc,
		ruWriteFunc	writeCb
	)

Allow substituting fputs call with custom implementation.

Mainly used for testing.

Parameters

rsc	ruSinkCtx to update.
writeCb	Custom write callback function or NULL to revert to standard fputs.

Returns

Status of the operation.

ruStdErrLogSink()

RUAPI void ruStdErrLogSink	(	perm_ptr	udata,
		uint32_t	logLevel,
		trans_chars	msg
	)

A convenience logging implementation that logs to stderr.

Parameters

udata	User data. This is ignored in this function.
logLevel	Log level pertaining to this message.
msg	The message to log.

ruStopLogger()

RUAPI void ruStopLogger

(

void

)

Stop the current logger and flush the queue before returning.