log.h File Reference

#include <inttypes.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>

Go to the source code of this file.

Data Structures
struct	cobaro_log
	Log information structure. More...

Macros
#define	COBARO_LOG_PARAM_MAX   (8)
	Number of parameters in a log message structure.

Typedefs
typedef struct cobaro_log *	cobaro_log_t
	Log structure pointer type.
typedef struct cobaro_loghandle *	cobaro_loghandle_t
	Opaque log handle type.

Enumerations
enum	cobaro_log_types { COBARO_STRING = 1, COBARO_INTEGER = 2, COBARO_REAL = 3, COBARO_IPV4 = 4 }
	Type discriminator for parameter values in logs. More...
enum	cobaro_log_levels {   COBARO_LOG_EMERG = 0, COBARO_LOG_ALERT, COBARO_LOG_CRIT, COBARO_LOG_ERR,   COBARO_LOG_WARNING, COBARO_LOG_NOTICE, COBARO_LOG_INFO, COBARO_LOG_DEBUG,   COBARO_LOG_LEVELS_COUNT }
	Log levels as they come from syslog(3). More...

Functions
char *	cobaro_log_version (void)
	Printable version number.
cobaro_loghandle_t	cobaro_log_init (char **messages)
	Initialize the logging infrastructure. More...
void	cobaro_log_messages_set (cobaro_loghandle_t lh, char **messages)
	Set the message catalog in use (in case you want to change language). More...
void	cobaro_log_fini (cobaro_loghandle_t lh)
	Finalize the logging infrastructure. More...
cobaro_log_t	cobaro_log_claim (cobaro_loghandle_t lh)
	Acquire a log structure from the handle's free list. More...
void	cobaro_log_set_string (cobaro_log_t log, int argnum, const char *source)
	Helper function for setting a string parameter. More...
void	cobaro_log_set_integer (cobaro_log_t log, int argnum, int64_t source)
	Helper function for setting an integer parameter. More...
void	cobaro_log_set_double (cobaro_log_t log, int argnum, double source)
	Helper function for setting an double parameter. More...
void	cobaro_log_set_ipv4 (cobaro_log_t log, int argnum, uint32_t source)
	Helper function for setting an IPv4 parameter. More...
void	cobaro_log_publish (cobaro_loghandle_t lh, cobaro_log_t log)
	Publish a log_t relinqushing its memory. More...
cobaro_log_t	cobaro_log_next (cobaro_loghandle_t lh)
	Receive a cobaro_log_t if available. More...
void	cobaro_log_return (cobaro_loghandle_t lh, cobaro_log_t log)
	Return a log structure to the free list. More...
bool	cobaro_log (cobaro_loghandle_t lh, cobaro_log_t log)
	Emit a log to the loghandle's default destination. More...
void	cobaro_log_to_syslog (cobaro_loghandle_t lh, cobaro_log_t log)
	Log a message to syslog. More...
int	cobaro_log_to_file (cobaro_loghandle_t lh, cobaro_log_t log, FILE *f)
	Log a message to file. More...
int	cobaro_log_to_string (cobaro_loghandle_t lh, cobaro_log_t log, char *buffer, size_t buflen)
	Log a message to a string. More...
bool	cobaro_log_loglevel_set (cobaro_loghandle_t lh, int level)
	Set the log level below which we should ignore logs. More...
bool	cobaro_log_file_set (cobaro_loghandle_t lh, FILE *f)
	Set the default log destination to be a file handle. More...
bool	cobaro_log_syslog_set (cobaro_loghandle_t lh)
	Set the default log destination to be syslog. More...

Enumeration Type Documentation

enum cobaro_log_levels

Log levels as they come from syslog(3).

Enumerator
COBARO_LOG_EMERG	System is unusable.
COBARO_LOG_ALERT	Action must be taken immediately.
COBARO_LOG_CRIT	Critical conditions.
COBARO_LOG_ERR	Error conditions.
COBARO_LOG_WARNING	Warning conditions.
COBARO_LOG_NOTICE	Normal but significant condition.
COBARO_LOG_INFO	Informational.
COBARO_LOG_DEBUG	Debug-level messages.
COBARO_LOG_LEVELS_COUNT	Iterator useful.

enum cobaro_log_types

Type discriminator for parameter values in logs.

Enumerator
COBARO_STRING	Value is a string.
COBARO_INTEGER	Value is a signed integer.
COBARO_REAL	Value is a double.
COBARO_IPV4	Value is an IP address (in 32 bit network format).

Function Documentation

bool cobaro_log	(	cobaro_loghandle_t	lh,
		cobaro_log_t	log
	)

Emit a log to the loghandle's default destination.

Only the first 1024 bytes of a log message will be written. If that is insufficient then use cobaro_log_to_string() and log directly.

Parameters

[in]	lh	Log handle to log with.
[in]	log	Pointer to log structure.

Returns

true on success, false on any failure.

cobaro_log_t cobaro_log_claim

(

cobaro_loghandle_t

lh

)

Acquire a log structure from the handle's free list.

The log handle maintains set of log structures that can be passed between threads to forward a log message for reporting. This function acquires a log structure from this free list. On return, you have control over its memory.

Parameters

[in]

lh

Log handle to fetch from.

Returns

Pointer to log structure on success. NULL if no log structures are available from the handle. This means that the logging system is congested, and the caller should simply continue its work without logging.

bool cobaro_log_file_set	(	cobaro_loghandle_t	lh,
		FILE *	f
	)

Set the default log destination to be a file handle.

Parameters

[in]	lh	Log handle in use.
[in]	f	File handle to log to.

Returns

true on success, false on failure.

void cobaro_log_fini

(

cobaro_loghandle_t

lh

)

Finalize the logging infrastructure.

Parameters

[in]

lh

Log handle to clean up.

cobaro_loghandle_t cobaro_log_init

(

char **

messages

)

Initialize the logging infrastructure.

Must be called once before logging. By default logging is to stdout at level LOG_INFO.

Parameters

[in]

messages

Array of message format strings. See test/messages.[ch] for examples.

Returns

Valid log handle on success, NULL on failure.

bool cobaro_log_loglevel_set	(	cobaro_loghandle_t	lh,
		int	level
	)

Set the log level below which we should ignore logs.

Parameters

[in]	lh	Log handle in use.
[in]	level	Level to log below, see syslog(3) for defined values. Default is LOG_INFO.

Returns

true on success, false on failure.

void cobaro_log_messages_set	(	cobaro_loghandle_t	lh,
		char **	messages
	)

Set the message catalog in use (in case you want to change language).

Parameters

[in]	lh	Log handle to set messages catalog for.
[in]	messages	Array of message format strings. See test/messages.[ch] for examples.

Returns

Valid log handle on success, NULL on failure.

cobaro_log_t cobaro_log_next

(

cobaro_loghandle_t

lh

)

Receive a cobaro_log_t if available.

Parameters

[in]

lh

Log handle to receive a log from.

Returns

NULL if nothing waiting, otherwise pointer to cobaro_log structure to be processed.

void cobaro_log_publish	(	cobaro_loghandle_t	lh,
		cobaro_log_t	log
	)

Publish a log_t relinqushing its memory.

Parameters

[in]	lh	Log handle to publish to.
[in]	log	Pointer to log object. This relinquishes control of the memory.

void cobaro_log_return	(	cobaro_loghandle_t	lh,
		cobaro_log_t	log
	)

Return a log structure to the free list.

Parameters

[in]	lh	Log handle to receive a log from.
[in]	log	Pointer to log structure to be returned to free list.

void cobaro_log_set_double	(	cobaro_log_t	log,
		int	argnum,
		double	source
	)

Helper function for setting an double parameter.

Parameters

[in]	log	Log structure to populate.
[in]	argnum	Argument number (as in, n, being array index + 1).
[in]	source	Double/real value to set.

void cobaro_log_set_integer	(	cobaro_log_t	log,
		int	argnum,
		int64_t	source
	)

Helper function for setting an integer parameter.

Parameters

[in]	log	Log structure to populate.
[in]	argnum	Argument number (as in, n, being array index + 1).
[in]	source	Integer value to set.

void cobaro_log_set_ipv4	(	cobaro_log_t	log,
		int	argnum,
		uint32_t	source
	)

Helper function for setting an IPv4 parameter.

Parameters

[in]	log	Log structure to populate.
[in]	argnum	Argument number (as in, n, being array index + 1).
[in]	source	IPv4 address, in host byte order.

void cobaro_log_set_string	(	cobaro_log_t	log,
		int	argnum,
		const char *	source
	)

Helper function for setting a string parameter.

Ensures that the string is copied and terminated properly in a single line of code, rather than three.

Parameters

[in]	log	Log structure to populate.
[in]	argnum	Argument number (as in, n, being array index + 1).
[in]	source	C-string to copy to log structure's parameters.

bool cobaro_log_syslog_set

(

cobaro_loghandle_t

lh

)

Set the default log destination to be syslog.

Caller is responsible for calling openlog(ident, option, facility) and closelog(), see syslog(3).

Parameters

[in]

lh

Log handle in use.

Returns

true on success, false on failure.

int cobaro_log_to_file	(	cobaro_loghandle_t	lh,
		cobaro_log_t	log,
		FILE *	f
	)

Log a message to file.

Write the formatted log message, prepended with a timestamp, to the specified file. The timestamp uses the local timezone, and microsecond precision.

Only the first 1024 bytes of a log message will be written. If that is insufficient then use cobaro_log_to_string() and a suitable buffer and call syslog(3) directly.

Parameters

[in]	lh	Log handle in use.
[in]	log	Log to write.
[in]	f	File handle to write to, eg. stdout, stderr, or any other FILE pointer.

Returns

If successful, returns the number of characters written to the file. If nothing was written (because the configured log level is too high), it returns zero.

If there was an error, -1 is returned and an error code is available from errno. ENOSPC indicates that the formatted message (including timestamp) exceeded 1024 bytes. See fprintf(3) and write(2) for other possible errno values.

int cobaro_log_to_string	(	cobaro_loghandle_t	lh,
		cobaro_log_t	log,
		char *	buffer,
		size_t	buflen
	)

Log a message to a string.

The function will not write more than buflen bytes and will always NUL-terminate the string even if that means truncating the formatted message.

Parameters

[in]	lh	Log handle in use.
[in]	log	Log data.
[in,out]	buffer	Write the formatted log message to this character buffer.
[in]	buflen	Length of buffer in bytes.

Returns

Number of characters that would have been written including the terminating NUL had space been available.

If this value is more than 1024, buffer contains a truncated, but safely terminated, message.

void cobaro_log_to_syslog	(	cobaro_loghandle_t	lh,
		cobaro_log_t	log
	)

Log a message to syslog.

This call assumes your application has established and configured a syslog session using openlog(3).

Only the first 1024 bytes of a log message will be written. If that is insufficient then use cobaro_log_to_string() and a suitable buffer and call syslog(3) directly.

Parameters

[in]	lh	Log handle to receive a log from.
[in]	log	Log data.