CEE-enhanced syslog message generation

Manual section


Manual group

CEE-enhanced syslog Manual


#include <umberlog.h>

void ul_openlog (const char *ident, int option, int facility);
void ul_set_log_flags (int flags);
void ul_closelog (void);

int ul_syslog (int priority, const char *format, ....);
int ul_vsyslog (int priority, const char *format, va_list ap);

void ul_legacy_syslog (int priority, const char *format, ...);
void ul_legacy_vsyslog (int priority, const char *format, va_list ap);

void ul_format (int priority, const char *format, ...);
void ul_vformat (int priority, const char *format, va_list ap);


ul_openlog() is a wrapper around the original openlog() function, which opens a connection to the system logger for a program.

ul_set_log_flags is to be used to set any combination of the new log flags described below.

ul_closelog() is similar to ul_openlog() in that it is a wrapper around the original closelog().

ul_legacy_syslog() and ul_legacy_vsyslog() are both thin layers over the original syslog() and vsyslog() functions. The only change these functions bring, are that the message they generate will be a CEE-enhanced message, with a JSON payload. See below for an explanation on what this means.

ul_syslog() and ul_vsyslog() are two new functions provided by the library, that have similar interface to the legacy syslog() functions, but they can be used to add arbitrary key-value pairs to the emitted message. After the msg_format format string, and any other parameters it refers to, there must be a NULL-terminated list of key, value format, format parameters. Each of these pairs, constructed from the key and the printf(3)-style value format will be added to the generated message.

Note that user-defined printf types defined by register_printf_type() are not supported.

ul_format() and ul_vformat() do the same as the syslog variants above, except the formatted payload is not sent to syslog, but returned as a newly allocated string.

In the LD_PRELOAD variant of the library, ul_openlog() and ul_closelog() override the system-default openlog() and closelog() respectively, while ul_legacy_syslog() and ul_legacy_vsyslog() override syslog() and vsyslog().


When successful, ul_syslog() and ul_vsyslog() return zero, while ul_format() and ul_vformat() return a character string.

On failure the former two will return non-zero, the latter two NULL, and set errno appropriately.


All of the improved syslog() functions, the legacy and overridden ones and the new ones too turn the original syslog message into a CEE-enabled JSON payload, with the original message put into the msg field, and any additional fields put into the same structure.

By default, unless the LOG_UL_NOIMPLICIT option flag is set, all of these functions will also add a few automatically discovered fields into the payload:


The process ID of the program, as returned by getpid().

facility, priority

The syslog facility and priority as a text string.


The identification set at the time of ul_openlog().

uid, gid

The user and group ID of the process.


The name of the originating host.


High-precision timestamp, in textual format. Included by default, but can be disabled by adding the LOG_UL_NOTIME flag to a ul_set_log_flags() call.

If caching is disabled (see LOG_UL_NOCACHE below), the pid, uid, gid, and host fields will be regenerated for every log message, otherwise they're cached for as long as possible.


The flag argument to ul_set_log_flags() is an OR of any of these flags:


Enable all automatically discovered fields. This is the default setting for the linkable library, but for the LD_PRELOAD variant, it can be changed at the library's configure time.


Disable adding any automatic discovered fields implicitly, and only include the message, and any specified key-value pairs in the generated message.


When implict fields are enabled, disable caching certain properties, that might change between the call to openlog() and the ul_syslog() invocation.


Disable the uid and gid caching when implicit fields are enabled, but do cache the rest.


Do not add a high-precision timestamp to the generated message when implicit fields are enabled.


status = ul_syslog(LOG_NOTICE, "Logged in user: %s", username,
                   "service", "%s", service,
                   "auth-method", "%s", auth_method,
                   "sessionid", "%d", session_id,



This page is part of the libumberlog project, and is available under the same 2-clause BSD license as the rest of the project.