In-memory logging

Log text messages to a circular memory buffer. More...

Functions
void	vmlog (const char *fmt, va_list ap)
	Log a message using a variable argument list. More...
void	mlog (const char *fmt,...)
	Log a message. More...
void	vmlog_nice (const char *fmt, va_list ap)
	Log a message using a variable argument list, if there is space to do so. More...
void	mlog_nice (const char *fmt,...)
	Log a message, if there is space to do so. More...
void	mlog_clear (void)
	Clear all data from the log. More...
void	mlog_dump (FILE *f)
	Format the log and write it to the supplied file pointer. More...
char *	mlog_get_line (int n)
	Format the Nth line of the log. More...

Detailed Description

Log text messages to a circular memory buffer.

A very fast text-centric circular log with deferred string formatting. Deferred formatting permits extremely low overhead logging; Each message is recorded using just four pointer sized writes. The log can be decoded either on the target device or using a external debugger.

This comes at a cost. In particular it imposes some significant restrictions on formatting compared to typical printf() influenced logging tools.

Function Documentation

void mlog	(	const char *	fmt,
			...
	)

Log a message.

In order to log a message mlog() captures the format string and up to three variadic arguments. It will not format the output during logging and as a result has an extremely low runtime overhead.

Some limitations arise as a result of deferring the string formatting. In particular:

1. Both the format string and any other strings to be displayed must never be overwritten with a different value. In practice this typically means they must either be string literals or pointers to constant data.
2. It is not possible to format floating point or long long values on 32-bit machines.
3. It is not possible to log 32-bit value on a 64-bit machine whose calling conventions do not pass the first three variadic arguments in registers.

If you do not understand #3 above, don't worry too much! The problems do not affect x86_64 systems.

Definition at line 47 of file mlog.c.

void mlog_clear

(

void

)

Clear all data from the log.

Definition at line 71 of file mlog.c.

void mlog_dump

(

FILE *

f

)

Format the log and write it to the supplied file pointer.

Definition at line 88 of file mlog.c.

char* mlog_get_line

(

int

n

)

Format the Nth line of the log.

The string returned is dynamically allocated and should be freed using free().

Definition at line 96 of file mlog.c.

void mlog_nice	(	const char *	fmt,
			...
	)

Log a message, if there is space to do so.

See mlog() for for further details.

Definition at line 62 of file mlog.c.

void vmlog	(	const char *	fmt,
		va_list	ap
	)

Log a message using a variable argument list.

See mlog() for for further details.

Definition at line 33 of file mlog.c.

void vmlog_nice	(	const char *	fmt,
		va_list	ap
	)

Log a message using a variable argument list, if there is space to do so.

See mlog() for for further details.

Definition at line 56 of file mlog.c.