Overview

A platform-neutral module enabling applications and libraries to log messages in either or both of syslog-compliant and human-readable format.

#include "lwpa_log.h"

This module can be used in two ways. Applications can use the lightweight lwpa_create_syslog_str() and lwpa_create_human_log_str() to create log messages with a header defined by the Syslog protocol or with a human-readable header defined by ETC.

This module can also be used to enable other libraries to log messages via a callback function. Library functions can take a set of parameters (lwpa_log_params) on initialization. They use these parameters and the lwpa_log() or lwpa_vlog() functions to call back to the application to log messages. The application can then decide what to do with these log messages (print to console, syslog, etc.)

Data Structures
struct	LwpaLogTimeParams
	A set of parameters which represent the current local time with millisecond resolution. More...

struct	LwpaSyslogParams
	A set of parameters for the syslog header. More...

struct	LwpaLogParams
	A set of parameters used for the lwpa_*log() functions. More...

Macros
#define	LWPA_LOG_NFACILITIES 24
	Current number of facilities.

#define	LWPA_LOG_FACMASK

#define	LWPA_LOG_FAC(p) (((p)&LWPA_LOG_FACMASK) >> 3)

#define	LWPA_LOG_PRIMASK 0x07 /* mask to extract priority part (internal) */

#define	LWPA_LOG_PRI(p) ((p)&LWPA_LOG_PRIMASK) /* extract priority */

#define	LWPA_LOG_MAKEPRI(fac, pri) (((fac) << 3) \| (pri))

#define	LWPA_LOG_MASK(pri) (1 << (pri)) /* mask for one priority */

#define	LWPA_LOG_UPTO(pri) ((1 << ((pri) + 1)) - 1) /* all priorities through pri */

#define	LWPA_LOG_HOSTNAME_MAX_LEN 256
	Max length of the hostname param.

#define	LWPA_LOG_APP_NAME_MAX_LEN 49
	Max length of the app_name param.

#define	LWPA_LOG_PROCID_MAX_LEN 129
	Max length of the procid param.

#define	LWPA_LOG_MSG_MAX_LEN 480
	Max length of a log message string passed to lwpa_log() or lwpa_vlog().

#define	LWPA_LOG_TIMESTAMP_LEN (10 /Date/ + 1 /T/ + 12 /Time/ + 6 /Offset/ + 1 /Nullterm/)
	The maximum length of the timestamp used in syslog and human-readable logging.

#define	LWPA_SYSLOG_HEADER_MAX_LEN
	The maximum length of the syslog header. More...

#define	LWPA_SYSLOG_STR_MIN_LEN LWPA_SYSLOG_HEADER_MAX_LEN
	The minimum length of a buffer passed to lwpa_create_syslog_str().

#define	LWPA_HUMAN_LOG_STR_MIN_LEN LWPA_LOG_TIMESTAMP_LEN
	The minimum length of a buffer passed to lwpa_create_human_log_str().

#define	LWPA_SYSLOG_STR_MAX_LEN (LWPA_SYSLOG_HEADER_MAX_LEN + LWPA_LOG_MSG_MAX_LEN)
	The maximum length of a syslog string that will be passed to an lwpa_log_callback function. More...

#define	LWPA_HUMAN_LOG_STR_MAX_LEN ((LWPA_LOG_TIMESTAMP_LEN - 1) + 1 /SP/ + LWPA_LOG_MSG_MAX_LEN)
	The maximum length of a human-readable string that will be passed to an lwpa_log_callback function. More...

#define	lwpa_setlogmask(logparamsptr, newlogmask) ((logparamsptr)->log_mask = newlogmask)

#define	lwpa_canlog(logparamsptr, pri) ((LWPA_LOG_MASK(pri) & (logparamsptr)->log_mask) != 0)

Typedefs
typedef struct LwpaLogTimeParams	LwpaLogTimeParams
	A set of parameters which represent the current local time with millisecond resolution.

typedef void(*	lwpa_log_callback) (void context, const char syslog_str, const char human_str, const char raw_str)
	Log callback function. More...

typedef void(*	lwpa_log_time_fn) (void context, LwpaLogTimeParams time_params)
	Time callback function. More...

typedef struct LwpaSyslogParams	LwpaSyslogParams
	A set of parameters for the syslog header.

typedef struct LwpaLogParams	LwpaLogParams
	A set of parameters used for the lwpa_*log() functions.

Enumerations
enum	lwpa_log_action_t { kLwpaLogCreateSyslog , kLwpaLogCreateHumanReadableLog , kLwpaLogCreateBoth }
	Which types of log message(s) the lwpa_log() and lwpa_vlog() functions create. More...

Functions
bool	lwpa_create_syslog_str (char buf, size_t buflen, const LwpaLogTimeParams time, const LwpaSyslogParams syslog_params, int pri, const char format,...)
	Create a log message with syslog header in the given buffer. More...

bool	lwpa_create_human_log_str (char buf, size_t buflen, const LwpaLogTimeParams time, const char *format,...)
	Create a log message with a human-readable header in the given buffer. More...

void	lwpa_sanitize_syslog_params (LwpaSyslogParams *params)
	Ensure that the given syslog parameters are compliant with the syslog RFC (modifying them if necessary). More...

bool	lwpa_validate_log_params (LwpaLogParams *params)
	Ensure that the given lwpa_log_params are valid. More...

void	lwpa_log (const LwpaLogParams params, int pri, const char format,...)
	Log a message from a library module. More...

void	lwpa_vlog (const LwpaLogParams params, int pri, const char format, va_list args)
	Log a message from a library module with the list of format arguments already generated. More...

Log Facility
#define	LWPA_LOG_KERN (0 << 3)
	Kernel messages.

#define	LWPA_LOG_USER (1 << 3)
	Random user-level messages.

#define	LWPA_LOG_MAIL (2 << 3)
	Mail system.

#define	LWPA_LOG_DAEMON (3 << 3)
	System daemons.

#define	LWPA_LOG_AUTH (4 << 3)
	Security/authorization messages.

#define	LWPA_LOG_SYSLOG (5 << 3)
	Messages generated internally by syslogd.

#define	LWPA_LOG_LPR (6 << 3)
	Line printer subsystem.

#define	LWPA_LOG_NEWS (7 << 3)
	Network news subsystem.

#define	LWPA_LOG_UUCP (8 << 3)
	UUCP subsystem.

#define	LWPA_LOG_CRON (9 << 3)
	Clock daemon.

#define	LWPA_LOG_AUTHPRIV (10 << 3)
	Security/authorization messages.

#define	LWPA_LOG_FTP (11 << 3)
	FTP daemon.

#define	LWPA_LOG_LOCAL0 (16 << 3)
	Reserved for local use.

#define	LWPA_LOG_LOCAL1 (17 << 3)
	Reserved for local use.

#define	LWPA_LOG_LOCAL2 (18 << 3)
	Reserved for local use.

#define	LWPA_LOG_LOCAL3 (19 << 3)
	Reserved for local use.

#define	LWPA_LOG_LOCAL4 (20 << 3)
	Reserved for local use.

#define	LWPA_LOG_LOCAL5 (21 << 3)
	Reserved for local use.

#define	LWPA_LOG_LOCAL6 (22 << 3)
	Reserved for local use.

#define	LWPA_LOG_LOCAL7 (23 << 3)
	Reserved for local use.

Log Priority
#define	LWPA_LOG_EMERG 0
	System is unusable.

#define	LWPA_LOG_ALERT 1
	Action must be taken immediately.

#define	LWPA_LOG_CRIT 2
	Critical conditions.

#define	LWPA_LOG_ERR 3
	Error conditions.

#define	LWPA_LOG_WARNING 4
	Warning conditions.

#define	LWPA_LOG_NOTICE 5
	Normal but significant condition.

#define	LWPA_LOG_INFO 6
	Informational.

#define	LWPA_LOG_DEBUG 7
	Debug-level messages.

Macro Definition Documentation

◆ LWPA_HUMAN_LOG_STR_MAX_LEN

#define LWPA_HUMAN_LOG_STR_MAX_LEN ((LWPA_LOG_TIMESTAMP_LEN - 1) + 1 /*SP*/ + LWPA_LOG_MSG_MAX_LEN)

The maximum length of a human-readable string that will be passed to an lwpa_log_callback function.

◆ LWPA_LOG_FACMASK

#define LWPA_LOG_FACMASK

Value:

0x03f8 /* Mask to extract facility part of a

prival. */

◆ LWPA_SYSLOG_HEADER_MAX_LEN

#define LWPA_SYSLOG_HEADER_MAX_LEN

Value:

  (5 /*PRIVAL*/ + 3 /*Version*/ + 1 /*SP*/ + (LWPA_LOG_TIMESTAMP_LEN - 1) /*Timestamp*/ + 1 /*SP*/ + \
   (LWPA_LOG_HOSTNAME_MAX_LEN - 1) + 1 /*SP*/ + (LWPA_LOG_APP_NAME_MAX_LEN - 1) + 1 /*SP*/ +         \
   (LWPA_LOG_PROCID_MAX_LEN - 1) + 1 /*SP*/ + 1 /*MSGID*/ + 1 /*SP*/ + 1 /*STRUCTURED-DATA*/ + 1 /*SP*/)

The maximum length of the syslog header.

◆ LWPA_SYSLOG_STR_MAX_LEN

#define LWPA_SYSLOG_STR_MAX_LEN (LWPA_SYSLOG_HEADER_MAX_LEN + LWPA_LOG_MSG_MAX_LEN)

The maximum length of a syslog string that will be passed to an lwpa_log_callback function.

Typedef Documentation

◆ lwpa_log_callback

typedef void(* lwpa_log_callback) (void *context, const char *syslog_str, const char *human_str, const char *raw_str)

Log callback function.

The function that library modules use to log messages. The application developer defines the function and determines where the messages go.

Parameters

[in]	context	Optional application-provided value that was previously passed to the library module.
[in]	syslog_str	Log string, formatted compliant to RFC 5424.
[in]	human_str	Log string, formatted for readability per ETC convention.
[in]	raw_str	The original log string that was passed to lwpa_log() or lwpa_vlog(). Will overlap with one of syslog_str or human_str.

◆ lwpa_log_time_fn

typedef void(* lwpa_log_time_fn) (void *context, LwpaLogTimeParams *time_params)

Time callback function.

A function by which the logging module can get the current local time.

Parameters

[in]	context	Optional application-provided value that was previously passed to the library module.
[out]	time_params	Fill this in with the current local time.

Enumeration Type Documentation

◆ lwpa_log_action_t

enum lwpa_log_action_t

Which types of log message(s) the lwpa_log() and lwpa_vlog() functions create.

Enumerator
kLwpaLogCreateSyslog	lwpa_log() and lwpa_vlog() create a syslog message and pass it back in the syslog_str parameter of the log callback.
kLwpaLogCreateHumanReadableLog	lwpa_log() and lwpa_vlog() create a human-readable log message and pass it back in the human_str parameter of the log callback.
kLwpaLogCreateBoth	lwpa_log() and lwpa_vlog() create both a syslog message and a human-readable log message and pass them back in the syslog_str and human_str parameters of the log callback.

Function Documentation

◆ lwpa_create_human_log_str()

bool lwpa_create_human_log_str	(	char *	buf,
		size_t	buflen,
		const LwpaLogTimeParams *	time,
		const char *	format,
			...
	)

Create a log message with a human-readable header in the given buffer.

Buffer must be at least LWPA_HUMAN_LOG_STR_MIN_LEN in length.

Parameters

[out]	buf	Buffer in which to build the log message.
[in]	buflen	Length in bytes of buf.
[in]	time	A set of time parameters representing the current time. If NULL, no timestamp will be added to the log message.
[in]	format	Log message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.

◆ lwpa_create_syslog_str()

bool lwpa_create_syslog_str	(	char *	buf,
		size_t	buflen,
		const LwpaLogTimeParams *	time,
		const LwpaSyslogParams *	syslog_params,
		int	pri,
		const char *	format,
			...
	)

Create a log message with syslog header in the given buffer.

Buffer must be at least LWPA_SYSLOG_STR_MIN_LEN in length.

Parameters

[out]	buf	Buffer in which to build the syslog message.
[in]	buflen	Length in bytes of buf.
[in]	time	A set of time parameters representing the current time. If NULL, no timestamp will be added to the log message.
[in]	syslog_params	A set of parameters for the syslog header.
[in]	pri	Priority of this log message.
[in]	format	Log message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.

◆ lwpa_log()

void lwpa_log	(	const LwpaLogParams *	params,
		int	pri,
		const char *	format,
			...
	)

Log a message from a library module.

Takes a printf-style format string which is formatted and passed to the application callback.

Parameters

[in]	params	The log parameters to be used for this message.
[in]	pri	Priority of this log message.
[in]	format	Log message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.

◆ lwpa_sanitize_syslog_params()

void lwpa_sanitize_syslog_params ( LwpaSyslogParams * params )

Ensure that the given syslog parameters are compliant with the syslog RFC (modifying them if necessary).

Sanitizes the three string fields (hostname, app_name and procid) by replacing characters that are not allowed by RFC 5424 with filler characters. Also ensures that the facility value is within the correct range (LWPA_LOG_NFACILITIES).

Parameters

[in,out] params Syslog params to sanitize.

◆ lwpa_validate_log_params()

bool lwpa_validate_log_params ( LwpaLogParams * params )

Ensure that the given lwpa_log_params are valid.

This also sanitizes the syslog params using lwpa_sanitize_syslog_params() if action is set to kLwpaLogCreateSyslog or kLwpaLogCreateBoth.

Parameters

[in,out] params lwpa_log_params to validate.

Returns: true (params are valid) or false (params are invalid).

◆ lwpa_vlog()

void lwpa_vlog	(	const LwpaLogParams *	params,
		int	pri,
		const char *	format,
		va_list	args
	)

Log a message from a library module with the list of format arguments already generated.

For normal usage, just use lwpa_log(). However, this function is useful if you want to create a wrapper function around lwpa_log() which also takes variable format arguments.

Parameters

[in]	params	The log parameters to be used for this message.
[in]	pri	Priority of this log message.
[in]	format	Log message with printf-style format specifiers.
[in]	args	Argument list for the format specifiers in format.

Overview

Data Structures

Macros

Typedefs

Enumerations

Functions

Log Facility

Log Priority

Macro Definition Documentation

◆ LWPA_HUMAN_LOG_STR_MAX_LEN

◆ LWPA_LOG_FACMASK

◆ LWPA_SYSLOG_HEADER_MAX_LEN

◆ LWPA_SYSLOG_STR_MAX_LEN

Typedef Documentation

◆ lwpa_log_callback

◆ lwpa_log_time_fn

Enumeration Type Documentation

◆ lwpa_log_action_t

Function Documentation

◆ lwpa_create_human_log_str()

◆ lwpa_create_syslog_str()

◆ lwpa_log()

◆ lwpa_sanitize_syslog_params()

◆ lwpa_validate_log_params()

◆ lwpa_vlog()