2 * UCW Library -- Logging
4 * (c) 1997--2009 Martin Mares <mj@ucw.cz>
5 * (c) 2008 Tomas Gavenciak <gavento@ucw.cz>
7 * This software may be freely distributed and used according to the terms
8 * of the GNU Lesser General Public License.
14 #include "ucw/clists.h"
16 /*** === Messages and streams ***/
19 * Inside the logging system, a log message is always represented by this structure.
22 char *m; // The formatted message itself, ending with \n\0
23 int m_len; // Length without the \0
24 struct tm *tm; // Current time
26 uns flags; // Category and other flags as passed to msg()
27 char *raw_msg; // Unformatted parts
33 * Each stream is represented by an instance of this structure.
36 char *name; // Optional name, allocated by the user (or constructor)
37 int regnum; // Stream number, already encoded by LS_SET_STRNUM(); -1 if closed
38 uns levels; // Bitmask of accepted severity levels (default: all)
39 uns types; // Bitmask of accepted message types (default: all)
40 uns msgfmt; // Formatting flags (LSFMT_xxx)
41 uns use_count; // Number of references to the stream
42 uns stream_flags; // Various other flags (LSFLAG_xxx)
43 int (*filter)(struct log_stream* ls, struct log_msg *m); // Filter function, return non-zero to discard the message
44 clist substreams; // Pass the message to these streams (simple_list of pointers)
45 int (*handler)(struct log_stream *ls, struct log_msg *m); // Called to commit the message, return 0 for success, errno on error
46 void (*close)(struct log_stream* ls); // Called upon log_close_stream()
47 // Private data of the handler follow
51 * Formatting flags specifying the format of the message passed to the handler.
54 LSFMT_LEVEL = 1, // severity level (one letter) */
55 LSFMT_TIME = 2, // date and time (YYYY-mm-dd HH:MM:SS) */
56 LSFMT_USEC = 4, // also micro-seconds */
57 LSFMT_TITLE = 8, // program title (log_title) */
58 LSFMT_PID = 16, // program PID (log_pid) */
59 LSFMT_LOGNAME = 32, // name of the log_stream */
60 LSFMT_TYPE = 64, // message type
63 #define LSFMT_DEFAULT (LSFMT_LEVEL | LSFMT_TIME | LSFMT_TITLE | LSFMT_PID) /** Default format **/
66 * General stream flags.
69 LSFLAG_ERR_IS_FATAL = 1, // When a logging error occurs, die() immediately
70 LSFLAG_ERR_REPORTED = 2, // A logging error has been already reported on this stream
76 * The @flags parameter of msg() is divided to several groups of bits (from the LSB):
77 * message severity level (`L_xxx`), destination stream, message type
78 * and control bits (e.g., `L_SIGHANDLER`).
81 enum ls_flagbits { // Bit widths of groups
88 enum ls_flagpos { // Bit positions of groups
90 LS_STRNUM_POS = LS_LEVEL_POS + LS_LEVEL_BITS,
91 LS_TYPE_POS = LS_STRNUM_POS + LS_STRNUM_BITS,
92 LS_CTRL_POS = LS_TYPE_POS + LS_TYPE_BITS,
95 enum ls_flagmasks { // Bit masks of groups
96 LS_LEVEL_MASK = ((1 << LS_LEVEL_BITS) - 1) << LS_LEVEL_POS,
97 LS_STRNUM_MASK = ((1 << LS_STRNUM_BITS) - 1) << LS_STRNUM_POS,
98 LS_TYPE_MASK = ((1 << LS_TYPE_BITS) - 1) << LS_TYPE_POS,
99 LS_CTRL_MASK = ((1 << LS_CTRL_BITS) - 1) << LS_CTRL_POS,
102 // "Get" macros (break flags to parts)
103 #define LS_GET_LEVEL(flags) (((flags) & LS_LEVEL_MASK) >> LS_LEVEL_POS) /** Extract severity level **/
104 #define LS_GET_STRNUM(flags) (((flags) & LS_STRNUM_MASK) >> LS_STRNUM_POS) /** Extract stream number **/
105 #define LS_GET_TYPE(flags) (((flags) & LS_TYPE_MASK) >> LS_TYPE_POS) /** Extract message type **/
106 #define LS_GET_CTRL(flags) (((flags) & LS_CTRL_MASK) >> LS_CTRL_POS) /** Extract control bits **/
108 // "Set" macros (parts to flags)
109 #define LS_SET_LEVEL(level) ((level) << LS_LEVEL_POS) /** Convert severity level to flags **/
110 #define LS_SET_STRNUM(strnum) ((strnum) << LS_STRNUM_POS) /** Convert stream number to flags **/
111 #define LS_SET_TYPE(type) ((type) << LS_TYPE_POS) /** Convert message type to flags **/
112 #define LS_SET_CTRL(ctrl) ((ctrl) << LS_CTRL_POS) /** Convert control bits to flags **/
114 #define LS_NUM_TYPES (1 << LS_TYPE_BITS)
116 /** Register a new message type and return the corresponding flag set (encoded by `LS_SET_TYPE`). **/
117 int log_register_type(const char *name);
119 /** Find a message type by name and return the corresponding flag set. Returns -1 if no such type found. **/
120 int log_find_type(const char *name);
122 /** Given a flag set, extract the message type ID and return its name. **/
123 char *log_type_name(uns flags);
125 /*** === Operations on streams ***/
128 * Allocate a new log stream with no handler and an empty substream list.
129 * Since struct log_stream is followed by private data, @size bytes of memory are allocated
130 * for the whole structure. See below for functions creating specific stream types.
132 struct log_stream *log_new_stream(size_t size);
135 * Decrement the use count of a stream. If it becomes zero, close the stream,
136 * free its memory, and unlink all its substreams.
138 int log_close_stream(struct log_stream *ls);
141 * Get a new reference on an existing stream. For convenience, the return value is
142 * equal to the argument @ls.
144 static inline struct log_stream *log_ref_stream(struct log_stream *ls)
151 * Link a substream to a stream. The substream gains a reference, preventing
152 * it from being freed until it is unlinked.
154 void log_add_substream(struct log_stream *where, struct log_stream *what);
157 * Unlink all occurrences of a substream @what from stream @where. Each
158 * occurrence loses a reference. If @what is NULL, all substreams are unlinked.
159 * Returns the number of unlinked substreams.
161 int log_rm_substream(struct log_stream *where, struct log_stream *what);
164 * Set formatting flags of a given stream and all its substreams. The flags are
165 * AND'ed with @mask and OR'ed with @data.
167 void log_set_format(struct log_stream *ls, uns mask, uns data);
170 * Find a stream by its registration number (in the format of logging flags).
171 * Returns NULL if there is no such stream.
173 struct log_stream *log_stream_by_flags(uns flags);
175 /** Return a pointer to the default stream (stream #0). **/
176 static inline struct log_stream *log_default_stream(void)
178 return log_stream_by_flags(0);
182 * Close all open streams, un-initialize the module, free all memory and
183 * reset the logging mechanism to use stderr only.
185 void log_close_all(void);
188 * === Logging to files
190 * All log files are open in append mode, which guarantees atomicity of write()
191 * even in multi-threaded programs.
194 struct log_stream *log_new_file(const char *path); /** Create a stream bound to a log file. **/
195 struct log_stream *log_new_fd(int fd); /** Create a stream bound to a file descriptor. **/
198 * When a time-based name of the log file changes, the logger switches to a new
199 * log file automatically. This can be sometimes inconvenient, so you can use
200 * this function to disable the automatic switches. The calls to this function
203 void log_switch_disable(void);
204 void log_switch_enable(void); /** Negate the effect of log_switch_disable(). **/
205 int log_switch(void); /** Switch log files manually. **/
208 * === Logging to syslog
210 * This log stream uses the libc interface to the system logging daemon (`syslogd`).
211 * This interface has several limitations:
213 * * Syslog are poorer than our scheme, so they are translated with a slight
214 * loss of information (most importantly, the distinction between local and
215 * remote messages is lost). If you are interested in details, search the
216 * source for syslog_level().
217 * * Syslog options (especially logging of PID with each message) must be fixed
218 * during initialization of the logger
219 * * Syslog provides its own formatting, so we turn off all formatting flags
220 * of the LibUCW logger. You can override this manually by setting the @msgfmt
221 * field of the log stream, but the result won't be nice.
222 * * Syslog does not support timestamps with sub-second precision.
226 * Create a log stream for logging to a selected syslog facility.
227 * The @options are passed to openlog(). (Beware, due to limitations of the
228 * syslog interface in libc, the @options are shared for all syslog streams
229 * and they are applied when the first stream is created.)
231 struct log_stream *log_new_syslog(const char *facility, int options);
234 * Verify that a facility of the given name exists. Return 1 if it does, 0 otherwise.
236 int log_syslog_facility_exists(const char *facility);
239 * === Configuring log streams
241 * If you use the LibUCW mechanism for parsing config files, you can let your
242 * user configure arbitrary log streams in the Logging section of the config file
243 * (see examples in the default config file). LibUCW automatically verifies that
244 * the configuration is consistent (this is performed in the commit hook of the
245 * config section), but it opens the streams only upon request. The following
246 * functions can be used to control that.
249 /** Open a log stream configured under the specified name and increase its use count. **/
250 struct log_stream *log_new_configured(const char *name);
252 /** Open a log stream configured under the specified name and use it as the default destination. **/
253 void log_configured(const char *name);
256 * Verify that a stream called @name was configured. If it wasn't, return an error
257 * message. This is intended to be used in configuration commit hooks.
259 char *log_check_configured(const char *name);