5.9.1 Logging

struct SerdLogField

A structured log field.

This can be used to pass additional information along with log messages. Syslog-compatible keys should be used where possible, otherwise, keys should be namespaced to prevent clashes.

Serd itself uses the following keys:

  • ERRNO

  • SERD_COL

  • SERD_FILE

  • SERD_LINE

  • SERD_STATUS

const char *key

Field name.

const char *value

Field value.

struct SerdLogEntry

A log entry (message).

This is the description of a log entry which is passed to log functions. It is only valid in the stack frame it appears in, and may not be copied.

An entry is a single self-contained message, so the string should not include a trailing newline.

const SerdLogField *fields

Extra log fields.

const char *fmt

Printf-style format string.

va_list *args

Arguments for fmt

SerdLogLevel level

Log level.

size_t n_fields

Number of fields

enum SerdLogLevel

Log message level, compatible with syslog.

enumerator SERD_LOG_LEVEL_EMERGENCY

Emergency, system is unusable.

enumerator SERD_LOG_LEVEL_ALERT

Action must be taken immediately.

enumerator SERD_LOG_LEVEL_CRITICAL

Critical condition.

enumerator SERD_LOG_LEVEL_ERROR

Error.

enumerator SERD_LOG_LEVEL_WARNING

Warning.

enumerator SERD_LOG_LEVEL_NOTICE

Normal but significant condition.

enumerator SERD_LOG_LEVEL_INFO

Informational message.

enumerator SERD_LOG_LEVEL_DEBUG

Debug message.

typedef SerdStatus (*SerdLogFunc)(void *handle, const SerdLogEntry *entry)

Sink function for log messages.

Parameters

  • handle – Handle for user data.

  • entry – Pointer to log entry description.

SerdStatus serd_quiet_error_func(void *handle, const SerdLogEntry *entry)

A SerdLogFunc that does nothing, for suppressing log output.

const char *serd_log_entry_get_field(const SerdLogEntry *entry, const char *key)

Return the value of the log field named key, or NULL if none exists.

void serd_world_set_log_func(SerdWorld *world, SerdLogFunc log_func, void *handle)

Set a function to be called with log messages (typically errors).

If no custom logging function is set, then messages are printed to stderr.

Parameters

  • world – World that will send log entries to the given function.

  • log_func – Log function to call for every log message. Each call to this function represents a complete log message with an implicit trailing newline.

  • handle – Opaque handle that will be passed to every invocation of log_func.

SerdStatus serd_world_logf(const SerdWorld *world, SerdLogLevel level, size_t n_fields, const SerdLogField *fields, const char *fmt, ...)

Write a message to the log.

This writes a single complete entry to the log, and so may not be used to print parts of a line like a more general printf-like function. There should be no trailing newline in fmt. Arguments following fmt should correspond to conversion specifiers in the format string as in printf from the standard C library.

Parameters

  • world – World to log to.

  • level – Log level.

  • n_fields – Number of entries in fields.

  • fields – An array of n_fields extra log fields.

  • fmt – Format string.

SerdStatus serd_world_vlogf(const SerdWorld *world, SerdLogLevel level, size_t n_fields, const SerdLogField *fields, const char *fmt, va_list args)

Write a message to the log with a va_list.

This is the same as serd_world_logf() except it takes format arguments as a va_list for composability.