trace

Writing trace messages. More...

Macros
#define	TRACE_LEVEL_DEBUG   1
	Identifier for debug trace level: also logs internal variables/states, only useful for developers.
#define	TRACE_LEVEL_DATA   2
	Identifier for data trace level: logs process data (e.g. More...
#define	TRACE_LEVEL_INFO   4
	Identifier for info trace level: informational (e.g. More...
#define	TRACE_LEVEL_FUNC_ENTER   8
	Identifier for function enter trace level.
#define	TRACE_LEVEL_FUNC_LEAVE   16
	Identifier for function leave trace level.
#define	TRACE_LEVEL_FUNC   24
	Identifier for function trace level.
#define	TRACE_LEVEL_NOTICE   32
	Identifier for notice trace level: normal but significant condition, e.g. More...
#define	TRACE_LEVEL_WARNING   64
	Identifier for warning trace level. More...
#define	TRACE_LEVEL_ERROR   128
	Identifier for error trace level: error conditions, e.g. More...
#define	TRACE_LEVEL_INSANE   256
	Identifier for insane trace level, produces a lot of output! This is used for cyclic events. More...
#define	TRACE_LEVEL_ALL   511
	Combination of all trace levels.
#define	TRACE_FAC_PLATFORM   1
	Identifier for platform facility.
#define	TRACE_FAC_NETWORK   2
	Identifier for network facility.
#define	TRACE_FAC_CRYPTO   4
	Identifier for crypto facility.
#define	TRACE_FAC_IPC   8
	Identifier for IPC facility.
#define	TRACE_FAC_BASE   16
	Identifier for base facility.
#define	TRACE_FAC_MEMORY   32
	Identifier for memory facility.
#define	TRACE_FAC_UATCP   64
	Identifier for UATCP facility.
#define	TRACE_FAC_ENCODER   128
	Identifier for encoder facility.
#define	TRACE_FAC_SESSION   256
	Identifier for session facility.
#define	TRACE_FAC_PROVIDER   512
	Identifier for provider facility.
#define	TRACE_FAC_APPLICATION   1024
	Identifier for application facility.
#define	TRACE_FAC_ADDRSPACE   2048
	Identifier for addressspace facility.
#define	TRACE_FAC_TIMER   4096
	Identifier for timer facility.
#define	TRACE_FAC_PKI   8192
	Identifier for timer facility.
#define	TRACE_FAC_SUBSCRIPTION   16384
	Identifier for subscription facility.
#define	TRACE_FAC_CLIENT   32768
	Identifier for client facility.
#define	TRACE_FAC_USERAPPLICATION   65536
	Reserved for the user application. More...
#define	TRACE_FAC_FILEFORMAT   (1 << 17)
	Identifier for fileformat facility.
#define	TRACE_FAC_ALL   ((1 << 18) - 1)
	Combination of all facilities.
#define	TRACE_DEBUG(facility, format, ...)   trace_log(TRACE_LEVEL_DEBUG, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with debug level.
#define	TRACE_DATA(facility, format, ...)   trace_log(TRACE_LEVEL_DATA, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with data level.
#define	TRACE_INFO(facility, format, ...)   trace_log(TRACE_LEVEL_INFO, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with info level.
#define	TRACE_NOTICE(facility, format, ...)   trace_log(TRACE_LEVEL_NOTICE, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with notic level.
#define	TRACE_WARNING(facility, format, ...)   trace_log(TRACE_LEVEL_WARNING, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with warning level.
#define	TRACE_ERROR(facility, format, ...)   trace_log(TRACE_LEVEL_ERROR, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with error level.
#define	TRACE_INSANE(facility, format, ...)
	Convenience define for tracing with insane level.
#define	TRACE_ENTER(facility, funcname)   trace_log(TRACE_LEVEL_FUNC_ENTER, facility, "> %s\n", funcname); trace_indent()
	Trace with function enter level, adds an indent.
#define	TRACE_RETURN(facility, funcname)   trace_unindent(); trace_log(TRACE_LEVEL_FUNC_LEAVE, facility, "< %s\n", funcname)
	Trace with function leave level, removes an indent.
#define	TRACE_RETURNERR(facility, funcname, result)   trace_unindent(); trace_log(TRACE_LEVEL_FUNC_LEAVE, facility, "< %s - return 0x%08X\n", funcname, result)
	Trace with function leave level, removes an indent and prints errorcode.
#define	TRACE_ENTERD(facility, funcname)   trace_log(TRACE_LEVEL_INSANE, facility, "> %s\n", funcname); trace_indent()
	Trace function enter with insane level, adds an indent.
#define	TRACE_RETURND(facility, funcname)   trace_unindent(); trace_log(TRACE_LEVEL_INSANE, facility, "< %s\n", funcname)
	Trace function leave with insane level, removes an indent.
#define	TRACE_RETURNERRD(facility, funcname, result)   trace_unindent(); trace_log(TRACE_LEVEL_INSANE, facility, "< %s - return 0x%08X\n", funcname, result)
	Trace function leave with insane level, removes an indent and prints errorcode.
#define	TRACE_HEXDUMP(facility, data, len)   trace_hexdump(TRACE_LEVEL_DATA, facility, data, len)

Functions
int	trace_openlog (int level_mask, int facility_mask)
	Initialize the trace backend. More...
void	trace_log (int level, int facility, const char *format,...) TRACE_FORMAT_ARGUMENT(3
	Write to trace. More...
void void	trace_hexdump (int level, int facility, const unsigned char *data, size_t count)
	Writes the hexdump of the given data to trace output. More...
void	trace_closelog (void)
	Close the trace backend.
int	trace_change_trace_level (int level_mask, int facility_mask)
	Change the trace level and facility. More...
int	trace_enabled (int level)
	Test if a certain trace level is enabled. More...
void	trace_indent (void)
	Add an indent to all further traces messages.
void	trace_unindent (void)
	Remove an indent from all furhter trace messages.

Detailed Description

Writing trace messages.

The SDK has multiple trace backends implemented, which can be selected using the cmake switch TRACE_BACKEND. Each of them writes the trace to a different location. To disable the trace completely the the cmake switch TRACE_ENABLED must be disabled.

Each trace message is written with a level to indicate the serverity of the message and a facility to assign the message to a component. Depending of the trace backend the trace messages may be prefixed with timestamps, the output can be colored, etc. See Trace Module for more general information about the different trace backends.

Macro Definition Documentation

TRACE_FAC_USERAPPLICATION

#define TRACE_FAC_USERAPPLICATION   65536

Reserved for the user application.

Not used in the SDK.

TRACE_LEVEL_DATA

#define TRACE_LEVEL_DATA   2

Identifier for data trace level: logs process data (e.g.

read/written values)

TRACE_LEVEL_ERROR

#define TRACE_LEVEL_ERROR   128

Identifier for error trace level: error conditions, e.g.

file access denied, out of memory, etc.

TRACE_LEVEL_INFO

#define TRACE_LEVEL_INFO   4

Identifier for info trace level: informational (e.g.

app started, shutdown, connect, disconnect, subcription created, ...)

TRACE_LEVEL_INSANE

#define TRACE_LEVEL_INSANE   256

Identifier for insane trace level, produces a lot of output! This is used for cyclic events.

TRACE_LEVEL_NOTICE

#define TRACE_LEVEL_NOTICE   32

Identifier for notice trace level: normal but significant condition, e.g.

authentication denied

TRACE_LEVEL_WARNING

#define TRACE_LEVEL_WARNING   64

Identifier for warning trace level.

e.g. certificate may expire soon, only 1MB of memory left, etc.

Function Documentation

trace_change_trace_level()

int trace_change_trace_level	(	int	level_mask,
		int	facility_mask
	)

Change the trace level and facility.

Parameters

level_mask	New trace level mask.
facility_mask	New trace facility mask.

Returns

Zero on success or errorcode on failure

trace_enabled()

int trace_enabled

(

int

level

)

Test if a certain trace level is enabled.

Parameters

level

Trace level to test.

Returns

Zero if the specified trace level is disabled

Test if a certain trace level is enabled.

If the trace level is disabled this function returns zero.

trace_hexdump()

void void trace_hexdump	(	int	level,
		int	facility,
		const unsigned char *	data,
		size_t	count
	)

Writes the hexdump of the given data to trace output.

Parameters

level	Level to trace to.
facility	Facility to trace to.
data	Pointer to data which whould be dumped.
count	Length of data in bytes.

trace_log()

void trace_log	(	int	level,
		int	facility,
		const char *	format,
			...
	)

Write to trace.

Parameters

level	Level to trace to.
facility	Facility to trace to.
format	Format specifier like for printf().

trace_openlog()

int trace_openlog	(	int	level_mask,
		int	facility_mask
	)

Initialize the trace backend.

Parameters

level_mask	Bitwise OR of trace levels to trace.
facility_mask	Bitwise OR of trace facilities to trace.

Returns

Zero on success or errorcode on failure