|is used to indicate that the stdlog_open() call shall use the default global options. If this option is given, on other options can be set. Trying to do so results in an error. Note that this option is not valid to for the stdlog_init() call.|
|request signal-safe mode. If and only if this is specified library calls are signal-safe. Some restrictions apply in signal-safe mode. See description below for details.|
The following facilities are supported. Please note that they are mimicked after the traditional syslog facilities, but liblogging-stdlog uses different numerical values. This is necessary to provide future enhancements. Do not use the LOG_xxx #defines from syslog.h but the following STDLOG_xxx defines:
STDLOG_KERN - kernel messages STDLOG_USER - random user-level messages STDLOG_MAIL - mail system STDLOG_DAEMON - system daemons STDLOG_AUTH - security/authorization messages STDLOG_SYSLOG - messages generated internally by syslogd STDLOG_LPR - line printer subsystem STDLOG_NEWS - network news subsystem STDLOG_UUCP - UUCP subsystem STDLOG_CRON - clock daemon STDLOG_AUTHPRIV - security/authorization messages (private) STDLOG_FTP - ftp daemon
STDLOG_LOCAL0 - reserved for application use STDLOG_LOCAL1 - reserved for application use STDLOG_LOCAL2 - reserved for application use STDLOG_LOCAL3 - reserved for application use STDLOG_LOCAL4 - reserved for application use STDLOG_LOCAL5 - reserved for application use STDLOG_LOCAL6 - reserved for application use STDLOG_LOCAL7 - reserved for application use
Regular applications should use facilities in the STDLOG_LOCALx range. Non-privileged applications may not be able to use all of the system-defined facilities. Note that it is also safe to refer to application specific facilities via
STDLOG_LOCAL0 + offset
if offset is in the range of 0 to 7.
The following severities are supported:
STDLOG_EMERG - system is unusable STDLOG_ALERT - action must be taken immediately STDLOG_CRIT - critical conditions STDLOG_ERR - error conditions STDLOG_WARNING - warning conditions STDLOG_NOTICE - normal but significant condition STDLOG_INFO - informational STDLOG_DEBUG - debug-level messages
These reflect the traditional syslog severity mappings. Note that
different output drivers may have different needs and may map
severities into a smaller set.
THREAD- AND SIGNAL-SAFENESS
These calls are thread- and signal-safe:
o stdlog_version() o stdlog_get_msgbuf_size() o stdlog_get_dflt_chanspec()
These calls are not thread- or signal-safe:
For stdlog_log(), stdlog_vlog(), stdlog_log_b(), and stdlog_vlog_b(), it depends:
|o||if the channel has been opened with the STDLOG_SIGSAFE option, the call is both thread-safe and signal-safe.|
|o||if the library has been initialized by stdlog_init() or the channel has been opened by stdlog_open(), the call is thread-safe but not signal-safe.|
|o||if the library has not been initialized and the default (NULL) channel is used, the call is neither thread- nor signal-safe.|
For stdlog_log_b() and stdlog_vlog_b() the caller must also ensure that the provided formatting buffer supports the desired thread- and signal-safeness. For example, if a static buffer is used, thread-safeness is not given. For signal-safeness, typically a buffer allocated on the signal handlers stack is needed.
For multi-threaded applications, it is highly recommended to initialize the library via stdlog_init() on the main thread before any other threads are started.
Thread- and signal-safeness, if given, does not require different channels. It is perfectly fine to use the same channel in multiple threads. Note however that interrupted system calls will not be retried. An error will be returned instead. This may happen if a thread is inside a stdlog_log() call while an async signal handler using that same call is activated. Depending on timing, the first call may or may not complete successfully. It is the callers chore to check return status and do retries if necessary.
Finally, thread- and signal-safeness depend on the log driver. At the time
of this writing,
the "syslog:" and "file:" drivers are thread- and signal-safe while the
current "journal:" driver is thread- but not signal-safe. To the best of
our knowledge, the systemd team is working on making the API we depend on
signal-safe. If this is done, the driver itself is also signal-safe (the
restriction results from the journal API).
RESRICTIONS IN SIGNAL-SAFE MODE
When signal-safeness is requested, the set of supported printf formats is restricted. This is due to the fact that the standard printf routines cannot be called and so a smaller signal-safe printf implementation that is part of liblogging-stdlog is used instead.
It has the following restrictions:
o flag characters are not supported o field width and precision fields are accepted but silently ignored o the following length modifiers are supported: l, ll, h, hh, z o the following conversion specifiers are supported: s, i, d, u, x, X, p, c, f (where f is always formatted as "%.2f") o only the following control character escapes are supported: \n, \r, \t, \\. Please note that it is not advisable to include control characters in log records. Log drivers and log back-end systems may remove them.
The channel is described via a single-line string. Currently, the following channels can be selected:
o "syslog:", which is the traditional syslog output to /dev/log o "uxsock:<name>", which writes messages to the local unix socket name. The message is formatted in traditional syslog-format. o "journal:", which emits messages via the native systemd journal API o "file:<name>", which writes messages in a syslog-like format to the file specified as name
If no channel specification is given, the default is "syslog:". The default channel can be set via the LIBLOGGING_STDLOG_DFLT_LOG_CHANNEL environment variable.
Not all output channel drivers are available on all platforms. For example,
the "journal:" driver is not available on BSD. It is highly suggested that
application developers never hard-code any channel specifiers inside
their code but rather permit the administrator to configure these. If there
is no pressing need to select different channel drivers, it is suggested
to rely on the default channel spec, which always can be set by the
When successful stdlog_init() and stdlog_log() return zero and something else otherwise. stdlog_open() returns a channel descriptor on success and NULL otherwise. In case of failure errno is set appropriately.
Note that the traditional syslog(3) API does not return any success state, so any failures are silently ignored. In most cases, this works sufficiently reliably. If this level of reliability is sufficient, the return code of stdlog_log() does not need to be checked. This is probably the case for most applications.
If finding out about the success of the logging operation is vital to the application, the return code can be checked. Note that you must not try to find out the exact failure cause. If the return is non-zero, something in the log system did not work correctly. It is suggested that the logging operation is re-tried in this case, and if it fails again it is suggested that the channel is closed and re-opened and then the operation re-tried. During failures, partial records may be logged. This is the same what could happen with syslog(3). Again, in general it should not be necessary to check the return code of stdlog_log().
The stdlog_deinit() and stdlog_close() calls do not return any status.
A typical single-threaded application just needs to know about the stdlog_log() call:
stdlog_log(NULL, STDLOG_NOTICE, "New session %d of user %s", sessid, username);
Being thread- and signal-safe requires a little bit more of setup:
/* on main thread */ status = stdlog_init(STDLOG_SIGSAFE);
/* here comes the rest of the code, including worker * thread startup. */
/* And do this in threads, signal handlers, etc: */ stdlog_log(NULL, STDLOG_NOTICE, "New session %d of user %s", sessid, username);
If you need just a small formatting buffer (or a large one), you can provide the memory yourself:
char buf; stdlog_log_b(NULL, STDLOG_NOTICE, buf, sizeof(buf), "New session %d of user %s", sessid, username);
This page is part of the liblogging project, and is available under the same BSD 2-clause license as the rest of the project.
Rainer Gerhards <email@example.com>