LIBLOGGING-STDLOG(3) standard logging library LIBLOGGING-STDLOG(3)NAME
liblogging-stdlog - standard logging library
SYNOPSIS
#include <liblogging/stdlog.h>
const char* stdlog_version(void);
int stdlog_init(int options);
void stdlog_deinit();
stdlog_channel_t stdlog_open(const char *ident,
const int options, const int facility,
const char *channelspec);
int stdlog_log(stdlog_channel_t channel, const int severity,
const char *fmt, ...);
int stdlog_log_b(stdlog_channel_t channel, const int severity,
char *buf, const size_t lenbuf,
const char *fmt, ...);
int stdlog_vlog(stdlog_channel_t channel, const int severity,
const char *fmt, va_list ap);
int stdlog_vlog_b(stdlog_channel_t channel, const int severity,
char *buf, const size_t lenbuf,
const char *fmt, va_list ap);
void stdlog_close(stdlog_channel_t channel);
size_t stdlog_get_msgbuf_size(void);
const char *stdlog_get_dflt_chanspec(void);
DESCRIPTIONstdlog_version() returns the version string for the library currently
being used (e.g. "1.0.2"). It may be called at any time. If a specific
(minimal) version of the library is required, it is suggested to do
runtime checks via stdlog_version() before stdlog_init() is called.
stdlog_init() is used to initialize the logging system. It must only
be called once during the lifetime of a process. If no special options
are desired, stdlog_init() is optional. If it is not called, the first
call to any of the other calls will initiate it. This feature is pri‐
marily for backward compatibility with how the legacy syslog(3) API
worked. It does not play well with multi-threaded applications. With
them, call stdlog_init() explicitly from the startup thread. The param‐
eter options contains one or more of the library options specified in
their own section below.
stdlog_deinit(void) is used to clean up resources including closing
file handles at library exit. No library calls are permitted after it
has been called. It's usage is optional if no cleanup is required (this
will leave resource leaks which will be reported by tools like val‐
grind).
stdlog_open() is used to open a log channel which can be used in con‐
secutive calls to stdlog_log(). The string given to ident is used to
identify the message source. It's handling is depending on the output
driver. For example, the file: and syslog: drivers prepend it to the
message, while the journal: driver ignores it (as the journal automati‐
cally identifies messages based on the application who submits them. In
general, you can think of it as being equivalent to the ident specified
in the traditional openlog(3) call. The value given in options controls
handling of the channel. It can be used to override options set during
stdlog_init(). Note that for signal-safeness you need to specify STD‐
LOG_SIGSAFE. The facility field contains a facility similar to the tra‐
ditional syslog facility. Again, it is driver-dependent on how this
field is actually used. The channelspec filed is a channel specifica‐
tion string, which allows to control the destination of this channel.
To use the default output channel specification, provide NULL to chan‐
nelspec. Doing so is highly suggested if there is no pressing need to
do otherwise.
stdlog_close() is used to close the associated channel. The channel
specifier must not be used after stdlog_close() has been called. If
done so, unpredictable behavior will happen, as the memory it points to
has been free'ed.
stdlog_log() is the equivalent to the syslog(3) call. It offers a simi‐
lar interface, but there are notable differences. The channel parameter
is used to specify the log channel to use to. Use NULL to select the
default channel. This is sufficient for most applications. The severity
field contains a syslog-like severity. The remaining arguments are a
format, as in printf(3) and any arguments required by the format. Note
that some restrictions apply to the format in signal-safe mode
(described below). The stdlog_log() supports log message sizes of
slightly less than 4KiB. The exact size depends on the log driver and
parameters specified in stdlog_open(). The reason is that the log driv‐
ers may need to add headers and trailers to the message text, and this
is done inside the same 4KiB buffer that is also used for the actual
message text. For example, the "syslog:" driver adds a traditional sys‐
log header, which among others contains the ident string provided by
stdlog_open(). If the complete log message does not fit into the buf‐
fer, it is silently truncated. The formatting buffer is allocated on
the stack.
Note that the 4Kib buffer size is a build time default. As such, dis‐
tributions may change it. To obtain the size limit that the linked in
instance of libloggin-stdlog was build with, use stdlog_get_msg‐
buf_size(). You may also use the stdlogctl(1) utility to find out the
build time settings for the installed version of liblogging-stdlog.
stdlog_log_b() is almost equivalent to stdlog_log(), except that the
caller can provide a formatting work buffer. This is done via the buf
and buflen parameters. This permits to use both smaller and larger buf‐
fer sizes. For embedded systems (or signal handlers), this may be con‐
venient to reduce the amount of stack space required. Also, it is use‐
ful if very large messages are to be logged. Note that while there is
no upper limit on the buffer size per se, the log drivers may have some
limits. In general, up to 64KiB of buffer should work with all drivers.
The stdlog_vlog() and stdlog_vlog_b() calls are equivalent to std‐
log_log() and stdlog_log_b() except that they take a va_list argument.
Use stdlog_get_dflt_chanspec() to obtain the default channel specifica‐
tion. This must be called only after stdlog_init() has been called.
OPTIONS
Options modify library behavior. They can be specified in stdlog_init()
and stdlog_open() calls. The stdlog_init() call is used to set default
options. These are applied if channels are automatically created or the
STDLOG_USE_DFLT_OPTS option is used in stdlog_open(). Otherwise,
options provided to stdlog_open() are not affected by the global option
set.
The following options can be given:
STDLOG_USE_DFLT_OPTS
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.
STDLOG_SIGSAFE
request signal-safe mode. If and only if this is specified
library calls are signal-safe. Some restrictions apply in sig‐
nal-safe mode. See description below for details.
FACILITIES
The following facilities are supported. Please note that they are mim‐
icked 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 sys‐
tem-defined facilities. Note that it is also safe to refer to applica‐
tion specific facilities via
STDLOG_LOCAL0 + offset
if offset is in the range of 0 to 7.
SEVERITY
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 dif‐
ferent 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:
· stdlog_version()
· stdlog_get_msgbuf_size()
· stdlog_get_dflt_chanspec()
These calls are not thread- or signal-safe:
· stdlog_init()
· stdlog_deinit()
· stdlog_open()
· stdlog_close()
For stdlog_log(), stdlog_vlog(), stdlog_log_b(), and stdlog_vlog_b(),
it depends:
· if the channel has been opened with the STDLOG_SIGSAFE option, the
call is both thread-safe and signal-safe.
· 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.
· if the library has not been initialized and the default (NULL) chan‐
nel 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 sig‐
nal-safeness. For example, if a static buffer is used, thread-safeness
is not given. For signal-safeness, typically a buffer allocated on the
signal handler's 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 chan‐
nels. 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 caller's 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 sig‐
nal-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 rou‐
tines cannot be called and so a smaller signal-safe printf implementa‐
tion that is part of liblogging-stdlog is used instead.
It has the following restrictions:
· flag characters are not supported
· field width and precision fields are accepted but silently ignored
· the following length modifiers are supported: l, ll, h, hh, z
· the following conversion specifiers are supported: s, i, d, u, x, X,
p, c, f (where f is always formatted as "%.2f")
· 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.
CHANNEL SPECIFICATIONS
The channel is described via a single-line string. Currently, the fol‐
lowing channels can be selected:
· "syslog:", which is the traditional syslog output to /dev/log
· "uxsock:<name>", which writes messages to the local unix socket name.
The message is formatted in traditional syslog-format.
· "journal:", which emits messages via the native systemd journal API
· "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 spec‐
ifiers inside their code but rather permit the administrator to config‐
ure 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 system administrator.
RETURN VALUE
When successful stdlog_init() and stdlog_log() return zero and some‐
thing else otherwise. stdlog_open() returns a channel descriptor on
success and NULL otherwise. In case of failure errno is set appropri‐
ately.
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 proba‐
bly 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.
EXAMPLES
A typical single-threaded application just needs to know about the std‐
log_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[512];
stdlog_log_b(NULL, STDLOG_NOTICE, buf, sizeof(buf),
"New session %d of user %s", sessid, username);
SEE ALSOstdlogctl(1), syslog(3)COPYRIGHT
This page is part of the liblogging project, and is available under the
same BSD 2-clause license as the rest of the project.
AUTHOR
Rainer Gerhards <rgerhards@adiscon.com>
2014-02-22 LIBLOGGING-STDLOG(3)
