1LIBLOGGING-STDLOG(3) standard logging library LIBLOGGING-STDLOG(3)
2
6 liblogging-stdlog - standard logging library
7
9 #include <liblogging/stdlog.h>
10 const char* stdlog_version(void);
12 int stdlog_init(int options);
14 void stdlog_deinit();
15 stdlog_channel_t stdlog_open(const char *ident,
17 const int options, const int facility,
18 const char *channelspec);
19 int stdlog_log(stdlog_channel_t channel, const int severity,
20 const char *fmt, ...);
21 int stdlog_log_b(stdlog_channel_t channel, const int severity,
22 char *buf, const size_t lenbuf,
23 const char *fmt, ...);
24 int stdlog_vlog(stdlog_channel_t channel, const int severity,
25 const char *fmt, va_list ap);
26 int stdlog_vlog_b(stdlog_channel_t channel, const int severity,
27 char *buf, const size_t lenbuf,
28 const char *fmt, va_list ap);
29 void stdlog_close(stdlog_channel_t channel);
30 size_t stdlog_get_msgbuf_size(void);
32 const char *stdlog_get_dflt_chanspec(void);
33
35 stdlog_version() returns the version string for the library currently
36 being used (e.g. "1.0.2"). It may be called at any time. If a specific
37 (minimal) version of the library is required, it is suggested to do
38 runtime checks via stdlog_version() before stdlog_init() is called.
39 stdlog_init() is used to initialize the logging system. It must only
41 be called once during the lifetime of a process. If no special options
42 are desired, stdlog_init() is optional. If it is not called, the first
43 call to any of the other calls will initiate it. This feature is pri‐
44 marily for backward compatibility with how the legacy syslog(3) API
45 worked. It does not play well with multi-threaded applications. With
46 them, call stdlog_init() explicitly from the startup thread. The param‐
47 eter options contains one or more of the library options specified in
48 their own section below.
49 stdlog_deinit(void) is used to clean up resources including closing
51 file handles at library exit. No library calls are permitted after it
52 has been called. It's usage is optional if no cleanup is required (this
53 will leave resource leaks which will be reported by tools like val‐
54 grind).
55 stdlog_open() is used to open a log channel which can be used in con‐
57 secutive calls to stdlog_log(). The string given to ident is used to
58 identify the message source. It's handling is depending on the output
59 driver. For example, the file: and syslog: drivers prepend it to the
60 message, while the journal: driver ignores it (as the journal automati‐
61 cally identifies messages based on the application who submits them. In
62 general, you can think of it as being equivalent to the ident specified
63 in the traditional openlog(3) call. The value given in options controls
64 handling of the channel. It can be used to override options set during
65 stdlog_init(). Note that for signal-safeness you need to specify STD‐
66 LOG_SIGSAFE. The facility field contains a facility similar to the tra‐
67 ditional syslog facility. Again, it is driver-dependent on how this
68 field is actually used. The channelspec filed is a channel specifica‐
69 tion string, which allows to control the destination of this channel.
70 To use the default output channel specification, provide NULL to chan‐
71 nelspec. Doing so is highly suggested if there is no pressing need to
72 do otherwise.
73 stdlog_close() is used to close the associated channel. The channel
75 specifier must not be used after stdlog_close() has been called. If
76 done so, unpredictable behavior will happen, as the memory it points to
77 has been free'ed.
78 stdlog_log() is the equivalent to the syslog(3) call. It offers a simi‐
80 lar interface, but there are notable differences. The channel parameter
81 is used to specify the log channel to use to. Use NULL to select the
82 default channel. This is sufficient for most applications. The severity
83 field contains a syslog-like severity. The remaining arguments are a
84 format, as in printf(3) and any arguments required by the format. Note
85 that some restrictions apply to the format in signal-safe mode
86 (described below). The stdlog_log() supports log message sizes of
87 slightly less than 4KiB. The exact size depends on the log driver and
88 parameters specified in stdlog_open(). The reason is that the log driv‐
89 ers may need to add headers and trailers to the message text, and this
90 is done inside the same 4KiB buffer that is also used for the actual
91 message text. For example, the "syslog:" driver adds a traditional sys‐
92 log header, which among others contains the ident string provided by
93 stdlog_open(). If the complete log message does not fit into the buf‐
94 fer, it is silently truncated. The formatting buffer is allocated on
95 the stack.
96 Note that the 4Kib buffer size is a build time default. As such, dis‐
98 tributions may change it. To obtain the size limit that the linked in
99 instance of libloggin-stdlog was build with, use stdlog_get_msg‐
100 buf_size(). You may also use the stdlogctl(1) utility to find out the
101 build time settings for the installed version of liblogging-stdlog.
102 stdlog_log_b() is almost equivalent to stdlog_log(), except that the
104 caller can provide a formatting work buffer. This is done via the buf
105 and buflen parameters. This permits to use both smaller and larger buf‐
106 fer sizes. For embedded systems (or signal handlers), this may be con‐
107 venient to reduce the amount of stack space required. Also, it is use‐
108 ful if very large messages are to be logged. Note that while there is
109 no upper limit on the buffer size per se, the log drivers may have some
110 limits. In general, up to 64KiB of buffer should work with all drivers.
111 The stdlog_vlog() and stdlog_vlog_b() calls are equivalent to std‐
113 log_log() and stdlog_log_b() except that they take a va_list argument.
114 Use stdlog_get_dflt_chanspec() to obtain the default channel specifica‐
116 tion. This must be called only after stdlog_init() has been called.
117
119 Options modify library behavior. They can be specified in stdlog_init()
120 and stdlog_open() calls. The stdlog_init() call is used to set default
121 options. These are applied if channels are automatically created or the
122 STDLOG_USE_DFLT_OPTS option is used in stdlog_open(). Otherwise,
123 options provided to stdlog_open() are not affected by the global option
124 set.
125 The following options can be given:
127 STDLOG_USE_DFLT_OPTS
129 is used to indicate that the stdlog_open() call shall use the
130 default global options. If this option is given, on other
131 options can be set. Trying to do so results in an error. Note
132 that this option is not valid to for the stdlog_init() call.
133 STDLOG_SIGSAFE
135 request signal-safe mode. If and only if this is specified
136 library calls are signal-safe. Some restrictions apply in sig‐
137 nal-safe mode. See description below for details.
138 STDLOG_PID
140 log the process identifier (PID) of the originator with each
141 message.
142
144 The following facilities are supported. Please note that they are mim‐
145 icked after the traditional syslog facilities, but liblogging-stdlog
146 uses different numerical values. This is necessary to provide future
147 enhancements. Do not use the LOG_xxx #defines from syslog.h but the
148 following STDLOG_xxx defines:
149 STDLOG_KERN - kernel messages
151 STDLOG_USER - random user-level messages
152 STDLOG_MAIL - mail system
153 STDLOG_DAEMON - system daemons
154 STDLOG_AUTH - security/authorization messages
155 STDLOG_SYSLOG - messages generated internally by syslogd
156 STDLOG_LPR - line printer subsystem
157 STDLOG_NEWS - network news subsystem
158 STDLOG_UUCP - UUCP subsystem
159 STDLOG_CRON - clock daemon
160 STDLOG_AUTHPRIV - security/authorization messages (private)
161 STDLOG_FTP - ftp daemon
162 STDLOG_LOCAL0 - reserved for application use
164 STDLOG_LOCAL1 - reserved for application use
165 STDLOG_LOCAL2 - reserved for application use
166 STDLOG_LOCAL3 - reserved for application use
167 STDLOG_LOCAL4 - reserved for application use
168 STDLOG_LOCAL5 - reserved for application use
169 STDLOG_LOCAL6 - reserved for application use
170 STDLOG_LOCAL7 - reserved for application use
171 Regular applications should use facilities in the STDLOG_LOCALx range.
173 Non-privileged applications may not be able to use all of the sys‐
174 tem-defined facilities. Note that it is also safe to refer to applica‐
175 tion specific facilities via
176 STDLOG_LOCAL0 + offset
178 if offset is in the range of 0 to 7.
180
182 The following severities are supported:
183 STDLOG_EMERG - system is unusable
185 STDLOG_ALERT - action must be taken immediately
186 STDLOG_CRIT - critical conditions
187 STDLOG_ERR - error conditions
188 STDLOG_WARNING - warning conditions
189 STDLOG_NOTICE - normal but significant condition
190 STDLOG_INFO - informational
191 STDLOG_DEBUG - debug-level messages
192 These reflect the traditional syslog severity mappings. Note that dif‐
194 ferent output drivers may have different needs and may map severities
195 into a smaller set.
196
198 These calls are thread- and signal-safe:
199 · stdlog_version()
201 · stdlog_get_msgbuf_size()
203 · stdlog_get_dflt_chanspec()
205 These calls are not thread- or signal-safe:
207 · stdlog_init()
209 · stdlog_deinit()
211 · stdlog_open()
213 · stdlog_close()
215 For stdlog_log(), stdlog_vlog(), stdlog_log_b(), and stdlog_vlog_b(),
217 it depends:
218 · if the channel has been opened with the STDLOG_SIGSAFE option, the
220 call is both thread-safe and signal-safe.
221 · if the library has been initialized by stdlog_init() or the channel
223 has been opened by stdlog_open(), the call is thread-safe but not
224 signal-safe.
225 · if the library has not been initialized and the default (NULL) chan‐
227 nel is used, the call is neither thread- nor signal-safe.
228 For stdlog_log_b() and stdlog_vlog_b() the caller must also ensure that
230 the provided formatting buffer supports the desired thread- and sig‐
231 nal-safeness. For example, if a static buffer is used, thread-safeness
232 is not given. For signal-safeness, typically a buffer allocated on the
233 signal handler's stack is needed.
234 For multi-threaded applications, it is highly recommended to initialize
236 the library via stdlog_init() on the main thread before any other
237 threads are started.
238 Thread- and signal-safeness, if given, does not require different chan‐
240 nels. It is perfectly fine to use the same channel in multiple threads.
241 Note however that interrupted system calls will not be retried. An
242 error will be returned instead. This may happen if a thread is inside a
243 stdlog_log() call while an async signal handler using that same call is
244 activated. Depending on timing, the first call may or may not complete
245 successfully. It is the caller's chore to check return status and do
246 retries if necessary.
247 Finally, thread- and signal-safeness depend on the log driver. At the
249 time of this writing, the "syslog:" and "file:" drivers are thread- and
250 signal-safe while the current "journal:" driver is thread- but not sig‐
251 nal-safe. To the best of our knowledge, the systemd team is working on
252 making the API we depend on signal-safe. If this is done, the driver
253 itself is also signal-safe (the restriction results from the journal
254 API).
255 RESRICTIONS IN SIGNAL-SAFE MODE
257 When signal-safeness is requested, the set of supported printf formats
258 is restricted. This is due to the fact that the standard printf rou‐
259 tines cannot be called and so a smaller signal-safe printf implementa‐
260 tion that is part of liblogging-stdlog is used instead.
261 It has the following restrictions:
263 · flag characters are not supported
265 · field width and precision fields are accepted but silently ignored
267 · the following length modifiers are supported: l, ll, h, hh, z
269 · the following conversion specifiers are supported: s, i, d, u, x, X,
271 p, c, f (where f is always formatted as "%.2f")
272 · only the following control character escapes are supported: \n, \r,
274 \t, \\. Please note that it is not advisable to include control
275 characters in log records. Log drivers and log back-end systems may
276 remove them.
277
279 The channel is described via a single-line string. Currently, the fol‐
280 lowing channels can be selected:
281 · "syslog:", which is the traditional syslog output to /dev/log
283 · "uxsock:<name>", which writes messages to the local unix socket name.
285 The message is formatted in traditional syslog-format.
286 · "journal:", which emits messages via the native systemd journal API
288 · "file:<name>", which writes messages in a syslog-like format to the
290 file specified as name
291 If no channel specification is given, the default is "syslog:". The
293 default channel can be set via the LIBLOGGING_STDLOG_DFLT_LOG_CHANNEL
294 environment variable.
295 Not all output channel drivers are available on all platforms. For
297 example, the "journal:" driver is not available on BSD. It is highly
298 suggested that application developers never hard-code any channel spec‐
299 ifiers inside their code but rather permit the administrator to config‐
300 ure these. If there is no pressing need to select different channel
301 drivers, it is suggested to rely on the default channel spec, which
302 always can be set by the system administrator.
303
305 When successful stdlog_init() and stdlog_log() return zero and some‐
306 thing else otherwise. stdlog_open() returns a channel descriptor on
307 success and NULL otherwise. In case of failure errno is set appropri‐
308 ately.
309 Note that the traditional syslog(3) API does not return any success
311 state, so any failures are silently ignored. In most cases, this works
312 sufficiently reliably. If this level of reliability is sufficient, the
313 return code of stdlog_log() does not need to be checked. This is proba‐
314 bly the case for most applications.
315 If finding out about the success of the logging operation is vital to
317 the application, the return code can be checked. Note that you must not
318 try to find out the exact failure cause. If the return is non-zero,
319 something in the log system did not work correctly. It is suggested
320 that the logging operation is re-tried in this case, and if it fails
321 again it is suggested that the channel is closed and re-opened and then
322 the operation re-tried. During failures, partial records may be logged.
323 This is the same what could happen with syslog(3). Again, in general it
324 should not be necessary to check the return code of stdlog_log().
325 The stdlog_deinit() and stdlog_close() calls do not return any status.
327
329 A typical single-threaded application just needs to know about the std‐
330 log_log() call:
331 stdlog_log(NULL, STDLOG_NOTICE, "New session %d of user %s",
333 sessid, username);
334 Being thread- and signal-safe requires a little bit more of setup:
336 /* on main thread */
338 status = stdlog_init(STDLOG_SIGSAFE);
339 /* here comes the rest of the code, including worker
341 * thread startup.
342 */
343 /* And do this in threads, signal handlers, etc: */
346 stdlog_log(NULL, STDLOG_NOTICE, "New session %d of user %s",
347 sessid, username);
348 If you need just a small formatting buffer (or a large one), you can
350 provide the memory yourself:
351 char buf[512];
353 stdlog_log_b(NULL, STDLOG_NOTICE, buf, sizeof(buf),
354 "New session %d of user %s", sessid, username);
355
357 stdlogctl(1), syslog(3)
358
360 This page is part of the liblogging project, and is available under the
361 same BSD 2-clause license as the rest of the project.
362
364 Rainer Gerhards <rgerhards@adiscon.com>
365 2014-02-22 LIBLOGGING-STDLOG(3)