EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
log (Logging)

Overview

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

#include "etcpal/log.h"

WARNING: This module must be explicitly initialized before using the following functions:

Initialize the module by calling etcpal_init() with the relevant feature mask:

etcpal_error_t etcpal_init(etcpal_features_t features)
Initialize the EtcPal library.
Definition: common.c:87
#define ETCPAL_FEATURE_LOGGING
Use the etcpal/log module.
Definition: common.h:130

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

char msg_buf[ETCPAL_LOG_STR_MAX_LEN];
EtcPalLogTimestamp current_time; // Fill in with current time...
"Something bad has happened: error code %d!", 42);
#define ETCPAL_LOG_WARNING
Warning conditions.
Definition: log.h:179
bool etcpal_create_log_str(char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, int pri, const char *format,...)
Create a log message with a human-readable prefix in the given buffer.
Definition: log.c:164
#define ETCPAL_LOG_STR_MAX_LEN
The maximum length of a string that will be passed via the human_readable member of an EtcPalLogStrin...
Definition: log.h:265
A set of parameters which represent the current local time with millisecond resolution.
Definition: log.h:272

The human-readable format consists of an ISO timestamp with the separating T replaced by a space, followed by a string indicating the priority and the message:

1970-01-01 00:00:00.001-06:00 [WARN] Something bad has happened: error code 42!

The syslog format is prefixed with a header which is compliant with RFC 5424. It is appropriate when an application needs to build syslog-format messages but there is no syslog daemon or library available. When such libraries are present, they handle formatting and building the header and thus this function should not be used.

The module also supports building a syslog format compliant with RFC 3164 (referred to here as "legacy syslog") for legacy product support. The RFC 3164 format is obsoleted by RFC 5424, and use of the legacy syslog format is not recommended in new code.

EtcPalSyslogParams my_syslog_params;
my_syslog_params.facility = ETCPAL_LOG_LOCAL1;
strcpy(my_syslog_params.hostname, "10.101.13.37");
strcpy(my_syslog_params.app_name, "My App");
sprintf(my_syslog_params.procid, "%d", my_proc_id);
etcpal_sanitize_syslog_params(&my_syslog_params); // Remove any invalid characters from the syslog params
char syslog_msg_buf[ETCPAL_SYSLOG_STR_MAX_LEN];
etcpal_create_syslog_str(syslog_msg_buf, ETCPAL_SYSLOG_STR_MAX_LEN, &current_time, &my_syslog_params,
ETCPAL_LOG_WARNING, "Something bad has happened: error code %d!", 42);
#define ETCPAL_LOG_LOCAL1
Reserved for local use.
Definition: log.h:154
void etcpal_sanitize_syslog_params(EtcPalSyslogParams *params)
Ensure that the given syslog parameters are compliant with the syslog RFC (modifying them if necessar...
Definition: log.c:328
bool etcpal_create_syslog_str(char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, const EtcPalSyslogParams *syslog_params, int pri, const char *format,...)
Create a log message with RFC 5424 syslog header in the given buffer.
Definition: log.c:218
#define ETCPAL_SYSLOG_STR_MAX_LEN
The maximum length of a syslog string that will be passed to an etcpal_log_callback function.
Definition: log.h:249
A set of parameters for the syslog header.
Definition: log.h:348
int facility
Syslog Facility; see RFC 5424 § 6.2.1.
Definition: log.h:350
char app_name[ETCPAL_LOG_APP_NAME_MAX_LEN]
Syslog APP-NAME; see RFC 5424 § 6.2.5.
Definition: log.h:354
char procid[ETCPAL_LOG_PROCID_MAX_LEN]
Syslog PROCID; see RFC 5424 § 6.2.6.
Definition: log.h:356
char hostname[ETCPAL_LOG_HOSTNAME_MAX_LEN]
Syslog HOSTNAME; see RFC 5424 § 6.2.4.
Definition: log.h:352

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 (EtcPalLogParams) on initialization. They use these parameters and the etcpal_log() or etcpal_vlog() functions to call back to the application to log messages. The application implements an EtcPalLogCallback from which it dispatches the log messages in whatever way it chooses (print to console, syslog, etc.), and an EtcPalLogTimeFn which is called to get the current time for each log message.

void my_time_callback(void* context, EtcPalLogTimestamp* timestamp)
{
// Fill in timestamp with the current time...
}
void my_log_callback(void* context, EtcPalLogStrings* log_strings)
{
// Use log_strings->syslog, log_strings->human_readable, and/or log_strings->raw as
// appropriate based on how I configured my log params.
}
// In an init function of some kind...
log_params.log_mask = ETCPAL_LOG_UPTO(ETCPAL_LOG_INFO); // Log up to and including INFO, excluding DEBUG.
log_params.log_fn = my_log_callback;
log_params.time_fn = my_time_callback;
// action is a bitmask representing the type of header(s) to create for each log message. For
// example, to create both a human-readable and syslog header:
strcpy(log_params.syslog_params.hostname, my_ip_addr_string);
strcpy(log_params.syslog_params.app_name, "My App");
// Pass to some library, maybe...
somelib_init(&log_params);
// Somewhere within the library, or elsewhere in my application...
etcpal_log(&log_params, ETCPAL_LOG_WARNING, "Something bad has happened: error code %d!", 42);
// Log message gets built and forwarded to my_log_callback, where I can do with it what I please.
#define ETCPAL_LOG_PARAMS_INIT
A default-value initializer for an EtcPalLogParams struct.
Definition: log.h:402
#define ETCPAL_LOG_CREATE_HUMAN_READABLE
Create a log string with a human-readable prefix including timestamp and severity.
Definition: log.h:340
#define ETCPAL_LOG_USER
Random user-level messages.
Definition: log.h:141
#define ETCPAL_LOG_INFO
Informational.
Definition: log.h:181
void etcpal_log(const EtcPalLogParams *params, int pri, const char *format,...)
Log a message.
Definition: log.c:405
#define ETCPAL_LOG_UPTO(pri)
Create a priority mask for all priorities through pri.
Definition: log.h:194
#define ETCPAL_LOG_CREATE_SYSLOG
Create a log string with a header that complies with RFC 5424.
Definition: log.h:342
A set of parameters used for the etcpal_*log() functions.
Definition: log.h:375
EtcPalSyslogParams syslog_params
The syslog header parameters.
Definition: log.h:381
EtcPalLogCallback log_fn
A callback function for the finished log string(s).
Definition: log.h:379
int action
What should be done when etcpal_log() or etcpal_vlog() is called.
Definition: log.h:377
int log_mask
A mask value that determines which priority messages can be logged.
Definition: log.h:383
EtcPalLogTimeFn time_fn
A callback function for the etcpal_log() and etcpal_vlog() functions to obtain the time from the appl...
Definition: log.h:388
The set of log strings passed with a call to an etcpal_log_callback function.
Definition: log.h:288

Data Structures

struct  EtcPalLogTimestamp
 A set of parameters which represent the current local time with millisecond resolution. More...
 
struct  EtcPalLogStrings
 The set of log strings passed with a call to an etcpal_log_callback function. More...
 
struct  EtcPalSyslogParams
 A set of parameters for the syslog header. More...
 
struct  EtcPalLogParams
 A set of parameters used for the etcpal_*log() functions. More...
 

Macros

#define ETCPAL_LOG_NFACILITIES   24
 Current number of facilities.
 
#define ETCPAL_LOG_FAC(p)   (((p) & ETCPAL_LOG_FACMASK) >> 3)
 Extract the facility part of a prival.
 
#define ETCPAL_LOG_PRI(p)   ((p) & ETCPAL_LOG_PRIMASK)
 Extract the priority part of a prival.
 
#define ETCPAL_LOG_MAKEPRI(fac, pri)   (((fac) << 3) | (pri))
 Make a prival from a facility and priority value.
 
#define ETCPAL_LOG_MASK(pri)   (1 << (pri))
 Create a priority mask for one priority.
 
#define ETCPAL_LOG_UPTO(pri)   ((1 << ((pri) + 1)) - 1)
 Create a priority mask for all priorities through pri.
 
#define ETCPAL_LOG_HOSTNAME_MAX_LEN   256u
 Max length of the hostname param.
 
#define ETCPAL_LOG_APP_NAME_MAX_LEN   49u
 Max length of the app_name param.
 
#define ETCPAL_LOG_PROCID_MAX_LEN   129u
 Max length of the procid param.
 
#define ETCPAL_RAW_LOG_MSG_MAX_LEN   480u
 Max length of a log message string passed to etcpal_log() or etcpal_vlog().
 
#define ETCPAL_LOG_TIMESTAMP_LEN   30u
 The maximum length of the timestamp used in syslog and human-readable logging.
 
#define ETCPAL_SYSLOG_HEADER_MAX_LEN
 The maximum length of the syslog header. More...
 
#define ETCPAL_SYSLOG_STR_MIN_LEN   ETCPAL_SYSLOG_HEADER_MAX_LEN
 The minimum length of a buffer passed to etcpal_create_syslog_str().
 
#define ETCPAL_LOG_STR_MIN_LEN   (ETCPAL_LOG_TIMESTAMP_LEN + 1u /*SP*/ + 6u /*pri*/ + 1u /*SP*/)
 The minimum length of a buffer passed to etcpal_create_log_str().
 
#define ETCPAL_SYSLOG_STR_MAX_LEN   (ETCPAL_SYSLOG_HEADER_MAX_LEN + ETCPAL_RAW_LOG_MSG_MAX_LEN)
 The maximum length of a syslog string that will be passed to an etcpal_log_callback function.
 
#define ETCPAL_LOG_STR_MAX_LEN   (8u + (ETCPAL_LOG_TIMESTAMP_LEN - 1u) + ETCPAL_RAW_LOG_MSG_MAX_LEN)
 The maximum length of a string that will be passed via the human_readable member of an EtcPalLogStrings struct.
 
#define ETCPAL_LOG_CREATE_HUMAN_READABLE   0x01
 Create a log string with a human-readable prefix including timestamp and severity.
 
#define ETCPAL_LOG_CREATE_SYSLOG   0x02
 Create a log string with a header that complies with RFC 5424.
 
#define ETCPAL_LOG_CREATE_LEGACY_SYSLOG   0x04
 Create a log string with a header that complies with RFC 3164.
 
#define ETCPAL_SYSLOG_PARAMS_INIT
 A default-value initializer for an EtcPalSyslogParams struct. More...
 
#define ETCPAL_LOG_PARAMS_INIT
 A default-value initializer for an EtcPalLogParams struct. More...
 

Typedefs

typedef struct EtcPalLogTimestamp EtcPalLogTimestamp
 A set of parameters which represent the current local time with millisecond resolution. More...
 
typedef struct EtcPalLogStrings EtcPalLogStrings
 The set of log strings passed with a call to an etcpal_log_callback function. More...
 
typedef void(* EtcPalLogCallback) (void *context, const EtcPalLogStrings *strings)
 Log callback function. More...
 
typedef void(* EtcPalLogTimeFn) (void *context, EtcPalLogTimestamp *timestamp)
 Time callback function. More...
 
typedef struct EtcPalSyslogParams EtcPalSyslogParams
 A set of parameters for the syslog header.
 
typedef struct EtcPalLogParams EtcPalLogParams
 A set of parameters used for the etcpal_*log() functions.
 

Functions

bool etcpal_create_log_str (char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, int pri, const char *format,...)
 Create a log message with a human-readable prefix in the given buffer. More...
 
bool etcpal_vcreate_log_str (char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, int pri, const char *format, va_list args)
 Create a log a message with a human-readable prefix in the given buffer. More...
 
bool etcpal_create_syslog_str (char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, const EtcPalSyslogParams *syslog_params, int pri, const char *format,...)
 Create a log message with RFC 5424 syslog header in the given buffer. More...
 
bool etcpal_vcreate_syslog_str (char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, const EtcPalSyslogParams *syslog_params, int pri, const char *format, va_list args)
 Create a log a message with RFC 5424 syslog header in the given buffer. More...
 
bool etcpal_create_legacy_syslog_str (char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, const EtcPalSyslogParams *syslog_params, int pri, const char *format,...)
 Create a log message with RFC 3164 syslog header in the given buffer. More...
 
bool etcpal_vcreate_legacy_syslog_str (char *buf, size_t buflen, const EtcPalLogTimestamp *timestamp, const EtcPalSyslogParams *syslog_params, int pri, const char *format, va_list args)
 Create a log a message with RFC 3164 syslog header in the given buffer. More...
 
void etcpal_sanitize_syslog_params (EtcPalSyslogParams *params)
 Ensure that the given syslog parameters are compliant with the syslog RFC (modifying them if necessary). More...
 
bool etcpal_validate_log_params (EtcPalLogParams *params)
 Ensure that the given EtcPalLogParams are valid. More...
 
bool etcpal_validate_log_timestamp (const EtcPalLogTimestamp *timestamp)
 Determine whether the given EtcPalLogTimestamp is valid. More...
 
bool etcpal_can_log (const EtcPalLogParams *params, int pri)
 Determine whether a priority level can be logged given the mask present in the log params. More...
 
void etcpal_log (const EtcPalLogParams *params, int pri, const char *format,...)
 Log a message. More...
 
void etcpal_vlog (const EtcPalLogParams *params, int pri, const char *format, va_list args)
 Log a message with the list of format arguments already generated. More...
 

Log Facility

#define ETCPAL_LOG_KERN   (0 << 3)
 Kernel messages.
 
#define ETCPAL_LOG_USER   (1 << 3)
 Random user-level messages.
 
#define ETCPAL_LOG_MAIL   (2 << 3)
 Mail system.
 
#define ETCPAL_LOG_DAEMON   (3 << 3)
 System daemons.
 
#define ETCPAL_LOG_AUTH   (4 << 3)
 Security/authorization messages.
 
#define ETCPAL_LOG_SYSLOG   (5 << 3)
 Messages generated internally by syslogd.
 
#define ETCPAL_LOG_LPR   (6 << 3)
 Line printer subsystem.
 
#define ETCPAL_LOG_NEWS   (7 << 3)
 Network news subsystem.
 
#define ETCPAL_LOG_UUCP   (8 << 3)
 UUCP subsystem.
 
#define ETCPAL_LOG_CRON   (9 << 3)
 Clock daemon.
 
#define ETCPAL_LOG_AUTHPRIV   (10 << 3)
 Security/authorization messages.
 
#define ETCPAL_LOG_FTP   (11 << 3)
 FTP daemon.
 
#define ETCPAL_LOG_LOCAL0   (16 << 3)
 Reserved for local use.
 
#define ETCPAL_LOG_LOCAL1   (17 << 3)
 Reserved for local use.
 
#define ETCPAL_LOG_LOCAL2   (18 << 3)
 Reserved for local use.
 
#define ETCPAL_LOG_LOCAL3   (19 << 3)
 Reserved for local use.
 
#define ETCPAL_LOG_LOCAL4   (20 << 3)
 Reserved for local use.
 
#define ETCPAL_LOG_LOCAL5   (21 << 3)
 Reserved for local use.
 
#define ETCPAL_LOG_LOCAL6   (22 << 3)
 Reserved for local use.
 
#define ETCPAL_LOG_LOCAL7   (23 << 3)
 Reserved for local use.
 

Log Priority

#define ETCPAL_LOG_EMERG   0
 System is unusable.
 
#define ETCPAL_LOG_ALERT   1
 Action must be taken immediately.
 
#define ETCPAL_LOG_CRIT   2
 Critical conditions.
 
#define ETCPAL_LOG_ERR   3
 Error conditions.
 
#define ETCPAL_LOG_WARNING   4
 Warning conditions.
 
#define ETCPAL_LOG_NOTICE   5
 Normal but significant condition.
 
#define ETCPAL_LOG_INFO   6
 Informational.
 
#define ETCPAL_LOG_DEBUG   7
 Debug-level messages.
 

Macro Definition Documentation

◆ ETCPAL_LOG_PARAMS_INIT

#define ETCPAL_LOG_PARAMS_INIT
Value:
{ \
0, NULL, ETCPAL_SYSLOG_PARAMS_INIT, 0, NULL, NULL \
}
#define ETCPAL_SYSLOG_PARAMS_INIT
A default-value initializer for an EtcPalSyslogParams struct.
Definition: log.h:368

A default-value initializer for an EtcPalLogParams struct.

Usage:

// Now fill in the relevant portions as necessary with your data...

◆ ETCPAL_SYSLOG_HEADER_MAX_LEN

#define ETCPAL_SYSLOG_HEADER_MAX_LEN
Value:
#define ETCPAL_LOG_PROCID_MAX_LEN
Max length of the procid param.
Definition: log.h:198
#define ETCPAL_LOG_APP_NAME_MAX_LEN
Max length of the app_name param.
Definition: log.h:197
#define ETCPAL_LOG_TIMESTAMP_LEN
The maximum length of the timestamp used in syslog and human-readable logging.
Definition: log.h:216
#define ETCPAL_LOG_HOSTNAME_MAX_LEN
Max length of the hostname param.
Definition: log.h:196

The maximum length of the syslog header.

◆ ETCPAL_SYSLOG_PARAMS_INIT

#define ETCPAL_SYSLOG_PARAMS_INIT
Value:
{ \
0, {'\0'}, {'\0'}, { '\0' } \
}

A default-value initializer for an EtcPalSyslogParams struct.

Usage:

// Now fill in the relevant portions as necessary with your data...

Typedef Documentation

◆ EtcPalLogCallback

typedef void(* EtcPalLogCallback) (void *context, const EtcPalLogStrings *strings)

Log callback function.

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

This function is called directly from the execution context of etcpal_log() and etcpal_vlog(). Be mindful of whether this function implementation has potential to block. If significant blocking is a possibility, consider queueing log messages and dispatching them from a worker thread.

Do not call etcpal_log() or etcpal_vlog() from this function; a deadlock will result.

Parameters
[in]contextOptional application-provided value that was previously passed to the library module.
[in]stringsStrings associated with the log message. Will contain valid strings corresponding to the log actions requested in the corresponding EtcPalLogParams struct.

◆ EtcPalLogStrings

The set of log strings passed with a call to an etcpal_log_callback function.

Any members not requested in the corresponding EtcPalLogParams struct will be NULL.

◆ EtcPalLogTimeFn

typedef void(* EtcPalLogTimeFn) (void *context, EtcPalLogTimestamp *timestamp)

Time callback function.

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

Parameters
[in]contextOptional application-provided value that was previously passed to the library module.
[out]timestampFill this in with the current local time.

◆ EtcPalLogTimestamp

A set of parameters which represent the current local time with millisecond resolution.

The valid ranges for each member can be validated using etcpal_validate_log_timestamp().

Function Documentation

◆ etcpal_can_log()

bool etcpal_can_log ( const EtcPalLogParams params,
int  pri 
)

Determine whether a priority level can be logged given the mask present in the log params.

This is useful to use as a guard around doing any conversions that are only for logging, e.g. converting addresses to strings – if the priority of the message can't be logged, then those conversions are just wasted work.

Parameters
[in]paramsThe log parameters to be checked.
[in]priPriority to check.
Returns
Whether this priority will be logged with the current mask setting.

◆ etcpal_create_legacy_syslog_str()

bool etcpal_create_legacy_syslog_str ( char *  buf,
size_t  buflen,
const EtcPalLogTimestamp timestamp,
const EtcPalSyslogParams syslog_params,
int  pri,
const char *  format,
  ... 
)

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

Buffer must be at least ETCPAL_SYSLOG_STR_MIN_LEN in length.

Parameters
[out]bufBuffer in which to build the syslog message.
[in]buflenLength in bytes of buf.
[in]timestampA timestamp representing the current time. If NULL, no timestamp will be added to the log message.
[in]syslog_paramsA set of parameters for the syslog header.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.

◆ etcpal_create_log_str()

bool etcpal_create_log_str ( char *  buf,
size_t  buflen,
const EtcPalLogTimestamp timestamp,
int  pri,
const char *  format,
  ... 
)

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

Buffer must be at least ETCPAL_LOG_STR_MIN_LEN in length.

Parameters
[out]bufBuffer in which to build the log message.
[in]buflenLength in bytes of buf.
[in]timestampA timestamp representing the current time. If NULL, no timestamp will be added to the log message.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.

◆ etcpal_create_syslog_str()

bool etcpal_create_syslog_str ( char *  buf,
size_t  buflen,
const EtcPalLogTimestamp timestamp,
const EtcPalSyslogParams syslog_params,
int  pri,
const char *  format,
  ... 
)

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

Buffer must be at least ETCPAL_SYSLOG_STR_MIN_LEN in length.

Parameters
[out]bufBuffer in which to build the syslog message.
[in]buflenLength in bytes of buf.
[in]timestampA timestamp representing the current time. If NULL, no timestamp will be added to the log message.
[in]syslog_paramsA set of parameters for the syslog header.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.

◆ etcpal_log()

void etcpal_log ( const EtcPalLogParams params,
int  pri,
const char *  format,
  ... 
)

Log a message.

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

Parameters
[in]paramsThe log parameters to be used for this message.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.

◆ etcpal_sanitize_syslog_params()

void etcpal_sanitize_syslog_params ( EtcPalSyslogParams 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 (ETCPAL_LOG_NFACILITIES).

Parameters
[in,out]paramsSyslog params to sanitize.

◆ etcpal_validate_log_params()

bool etcpal_validate_log_params ( EtcPalLogParams params)

Ensure that the given EtcPalLogParams are valid.

This also sanitizes the syslog params using etcpal_sanitize_syslog_params() if action is set to kEtcPalLogCreateSyslog or kEtcPalLogCreateBoth.

Parameters
[in,out]paramsetcpal_log_params to validate.
Returns
true (params are valid) or false (params are invalid).

◆ etcpal_validate_log_timestamp()

bool etcpal_validate_log_timestamp ( const EtcPalLogTimestamp timestamp)

Determine whether the given EtcPalLogTimestamp is valid.

Enforces the range rules defined in the structure documentation.

Parameters
[in]timestampTimestamp to validate.
Returns
Whether the timestamp represents a valid time.

◆ etcpal_vcreate_legacy_syslog_str()

bool etcpal_vcreate_legacy_syslog_str ( char *  buf,
size_t  buflen,
const EtcPalLogTimestamp timestamp,
const EtcPalSyslogParams syslog_params,
int  pri,
const char *  format,
va_list  args 
)

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

Buffer must be at least ETCPAL_SYSLOG_STR_MIN_LEN in length. This function is useful if you want to create a wrapper function around etcpal_create_syslog_str() which also takes variable format arguments.

Parameters
[out]bufBuffer in which to build the syslog message.
[in]buflenLength in bytes of buf.
[in]timestampA timestamp representing the current time. If NULL, no timestamp will be added to the log message.
[in]syslog_paramsA set of parameters for the syslog header.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.
[in]argsArgument list for the format specifiers in format.

◆ etcpal_vcreate_log_str()

bool etcpal_vcreate_log_str ( char *  buf,
size_t  buflen,
const EtcPalLogTimestamp timestamp,
int  pri,
const char *  format,
va_list  args 
)

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

Buffer must be at least ETCPAL_LOG_STR_MIN_LEN in length. This function is useful if you want to create a wrapper function around etcpal_create_log_str() which also takes variable format arguments.

Parameters
[out]bufBuffer in which to build the log message.
[in]buflenLength in bytes of buf.
[in]timestampA timestamp representing the current time. If NULL, no timestamp will be added to the log message.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.
[in]argsArgument list for the format specifiers in format.

◆ etcpal_vcreate_syslog_str()

bool etcpal_vcreate_syslog_str ( char *  buf,
size_t  buflen,
const EtcPalLogTimestamp timestamp,
const EtcPalSyslogParams syslog_params,
int  pri,
const char *  format,
va_list  args 
)

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

Buffer must be at least ETCPAL_SYSLOG_STR_MIN_LEN in length. This function is useful if you want to create a wrapper function around etcpal_create_syslog_str() which also takes variable format arguments.

Parameters
[out]bufBuffer in which to build the syslog message.
[in]buflenLength in bytes of buf.
[in]timestampA timestamp representing the current time. If NULL, no timestamp will be added to the log message.
[in]syslog_paramsA set of parameters for the syslog header.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers. Provide additional arguments as appropriate for format specifiers.
[in]argsArgument list for the format specifiers in format.

◆ etcpal_vlog()

void etcpal_vlog ( const EtcPalLogParams params,
int  pri,
const char *  format,
va_list  args 
)

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

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

Parameters
[in]paramsThe log parameters to be used for this message.
[in]priPriority of this log message.
[in]formatLog message with printf-style format specifiers.
[in]argsArgument list for the format specifiers in format.