/* * UCW Library -- Logging * * (c) 1997--2015 Martin Mares * (c) 2008 Tomas Gavenciak * * This software may be freely distributed and used according to the terms * of the GNU Lesser General Public License. */ #ifndef _UCW_LOG_H_ #define _UCW_LOG_H_ #include #ifdef CONFIG_UCW_CLEAN_ABI #define log_add_substream ucw_log_add_substream #define log_check_configured ucw_log_check_configured #define log_close_all ucw_log_close_all #define log_close_stream ucw_log_close_stream #define log_configured ucw_log_configured #define log_drop_stderr ucw_log_drop_stderr #define log_find_type ucw_log_find_type #define log_new_configured ucw_log_new_configured #define log_new_fd ucw_log_new_fd #define log_new_file ucw_log_new_file #define log_new_stream ucw_log_new_stream #define log_new_syslog ucw_log_new_syslog #define log_pass_filtered ucw_log_pass_filtered #define log_register_type ucw_log_register_type #define log_rm_substream ucw_log_rm_substream #define log_set_default_stream ucw_log_set_default_stream #define log_set_format ucw_log_set_format #define log_stream_by_flags ucw_log_stream_by_flags #define log_switch ucw_log_switch #define log_switch_disable ucw_log_switch_disable #define log_switch_enable ucw_log_switch_enable #define log_syslog_facility_exists ucw_log_syslog_facility_exists #define log_type_name ucw_log_type_name #endif /*** === Messages and streams ***/ /** * Inside the logging system, a log message is always represented by this structure. **/ struct log_msg { char *m; // The formatted message itself, ending with \n\0 int m_len; // Length without the \0 struct tm *tm; // Current time struct timeval *tv; uint flags; // Category and other flags as passed to msg() char *raw_msg; // Unformatted parts char *stime; char *sutime; uint depth; // Recursion depth bool error; // An error has occurred (e.g., an infinite loop in sub-streams) }; /** * Each stream is represented by an instance of this structure. **/ struct log_stream { char *name; // Optional name, allocated by the user (or constructor) int regnum; // Stream number, already encoded by LS_SET_STRNUM(); -1 if closed uint levels; // Bitmask of accepted severity levels (default: all) uint types; // Bitmask of accepted message types (default: all) uint msgfmt; // Formatting flags (LSFMT_xxx) uint use_count; // Number of references to the stream uint stream_flags; // Various other flags (LSFLAG_xxx) int (*filter)(struct log_stream* ls, struct log_msg *m); // Filter function, return non-zero to discard the message clist substreams; // Pass the message to these streams (simple_list of pointers) int (*handler)(struct log_stream *ls, struct log_msg *m); // Called to commit the message, return 0 for success, errno on error void (*close)(struct log_stream* ls); // Called upon log_close_stream() void *user_data; // Not used by the logging system // Private data of the handler follow }; /** * Formatting flags specifying the format of the message passed to the handler. **/ enum ls_fmt { LSFMT_LEVEL = 1, // severity level (one letter) */ LSFMT_TIME = 2, // date and time (YYYY-mm-dd HH:MM:SS) */ LSFMT_USEC = 4, // also micro-seconds */ LSFMT_TITLE = 8, // program title (log_title) */ LSFMT_PID = 16, // program PID (log_pid) */ LSFMT_LOGNAME = 32, // name of the log_stream */ LSFMT_TYPE = 64, // message type }; #define LSFMT_DEFAULT (LSFMT_LEVEL | LSFMT_TIME | LSFMT_TITLE | LSFMT_PID) /** Default format **/ /** * General stream flags. **/ enum ls_flag { LSFLAG_ERR_IS_FATAL = 1, // When a logging error occurs, die() immediately LSFLAG_ERR_REPORTED = 2, // A logging error has been already reported on this stream }; /*** * === Message flags * * The @flags parameter of <> is divided to several groups of bits (from the LSB): * message severity level (`L_xxx`), destination stream, message type * and control bits (e.g., `L_SIGHANDLER`). ***/ enum ls_flagbits { // Bit widths of groups LS_LEVEL_BITS = 8, LS_STRNUM_BITS = 16, LS_TYPE_BITS = 5, LS_CTRL_BITS = 3, }; enum ls_flagpos { // Bit positions of groups LS_LEVEL_POS = 0, LS_STRNUM_POS = LS_LEVEL_POS + LS_LEVEL_BITS, LS_TYPE_POS = LS_STRNUM_POS + LS_STRNUM_BITS, LS_CTRL_POS = LS_TYPE_POS + LS_TYPE_BITS, }; enum ls_flagmasks { // Bit masks of groups LS_LEVEL_MASK = ((1 << LS_LEVEL_BITS) - 1) << LS_LEVEL_POS, LS_STRNUM_MASK = ((1 << LS_STRNUM_BITS) - 1) << LS_STRNUM_POS, LS_TYPE_MASK = ((1 << LS_TYPE_BITS) - 1) << LS_TYPE_POS, LS_CTRL_MASK = ((1 << LS_CTRL_BITS) - 1) << LS_CTRL_POS, }; // "Get" macros (break flags to parts) #define LS_GET_LEVEL(flags) (((flags) & LS_LEVEL_MASK) >> LS_LEVEL_POS) /** Extract severity level **/ #define LS_GET_STRNUM(flags) (((flags) & LS_STRNUM_MASK) >> LS_STRNUM_POS) /** Extract stream number **/ #define LS_GET_TYPE(flags) (((flags) & LS_TYPE_MASK) >> LS_TYPE_POS) /** Extract message type **/ #define LS_GET_CTRL(flags) (((flags) & LS_CTRL_MASK) >> LS_CTRL_POS) /** Extract control bits **/ // "Set" macros (parts to flags) #define LS_SET_LEVEL(level) ((level) << LS_LEVEL_POS) /** Convert severity level to flags **/ #define LS_SET_STRNUM(strnum) ((strnum) << LS_STRNUM_POS) /** Convert stream number to flags **/ #define LS_SET_TYPE(type) ((type) << LS_TYPE_POS) /** Convert message type to flags **/ #define LS_SET_CTRL(ctrl) ((ctrl) << LS_CTRL_POS) /** Convert control bits to flags **/ #define LS_NUM_TYPES (1 << LS_TYPE_BITS) /** Register a new message type and return the corresponding flag set (encoded by `LS_SET_TYPE`). **/ int log_register_type(const char *name); /** Find a message type by name and return the corresponding flag set. Returns -1 if no such type found. **/ int log_find_type(const char *name); /** Given a flag set, extract the message type ID and return its name. **/ char *log_type_name(uint flags); /*** === Operations on streams ***/ /** * Allocate a new log stream with no handler and an empty substream list. * Since struct log_stream is followed by private data, @size bytes of memory are allocated * for the whole structure. See below for functions creating specific stream types. **/ struct log_stream *log_new_stream(size_t size); /** * Decrement the use count of a stream. If it becomes zero, close the stream, * free its memory, and unlink all its substreams. **/ int log_close_stream(struct log_stream *ls); /** * Get a new reference on an existing stream. For convenience, the return value is * equal to the argument @ls. **/ static inline struct log_stream *log_ref_stream(struct log_stream *ls) { ls->use_count++; return ls; } /** * Link a substream to a stream. The substream gains a reference, preventing * it from being freed until it is unlinked. **/ void log_add_substream(struct log_stream *where, struct log_stream *what); /** * Unlink all occurrences of a substream @what from stream @where. Each * occurrence loses a reference. If @what is NULL, all substreams are unlinked. * Returns the number of unlinked substreams. **/ int log_rm_substream(struct log_stream *where, struct log_stream *what); /** * Set formatting flags of a given stream and all its substreams. The flags are * AND'ed with @mask and OR'ed with @data. **/ void log_set_format(struct log_stream *ls, uint mask, uint data); /** * Find a stream by its registration number (in the format of logging flags). * Returns NULL if there is no such stream. **/ struct log_stream *log_stream_by_flags(uint flags); /** Return a pointer to the default stream (stream #0). **/ static inline struct log_stream *log_default_stream(void) { return log_stream_by_flags(0); } /** * Make the specified stream the default destination. * * In fact, it takes the fixed default stream and attaches @ls as its only * substream. If there were any other substreams, they are removed. * * Log streams created by <> or @log_configured() are made default * by calling this function. **/ void log_set_default_stream(struct log_stream *ls); /** * Close all open streams, un-initialize the module, free all memory and * reset the logging mechanism to use stderr only. **/ void log_close_all(void); /** * The filter function of a stream might want to modify the message * before passing it to the handler and/or substreams. In this case, * the filter should make a local copy of `struct log_msg`, call * @log_pass_filtered() on it and return true, so that the original * message will not be processed any further. **/ void log_pass_filtered(struct log_stream *ls, struct log_msg *m); /*** * === Logging to files * * All log files are open in append mode, which guarantees atomicity of write() * even in multi-threaded programs. ***/ struct log_stream *log_new_file(const char *path, uint flags); /** Create a stream bound to a log file. See `FF_xxx` for @flags. **/ struct log_stream *log_new_fd(int fd, uint flags); /** Create a stream bound to a file descriptor. See `FF_xxx` for @flags. **/ enum log_file_flag { /** Flags used for file-based logging **/ FF_FORMAT_NAME = 1, // Internal: Name contains strftime escapes FF_CLOSE_FD = 2, // Close the fd with the stream (use with log_new_fd()) FF_FD2_FOLLOWS = 4, // Maintain stderr as a clone of this stream }; /** * When a time-based name of the log file changes, the logger switches to a new * log file automatically. This can be sometimes inconvenient, so you can use * this function to disable the automatic switches. The calls to this function * can be nested. **/ void log_switch_disable(void); void log_switch_enable(void); /** Negate the effect of log_switch_disable(). **/ int log_switch(void); /** Switch log files manually. **/ /** * Drop stderr if it is not already redirected to a log file. * This is usually needed in daemons to make sure that the original * stderr does not stay open (stdin and stdout are dropped by our * <> automatically). More specifically, * it makes stderr a clone of stdout. **/ void log_drop_stderr(void); /*** * === Logging to syslog * * This log stream uses the libc interface to the system logging daemon (`syslogd`). * This interface has several limitations: * * * Syslog are poorer than our scheme, so they are translated with a slight * loss of information (most importantly, the distinction between local and * remote messages is lost). If you are interested in details, search the * source for syslog_level(). * * Syslog options (especially logging of PID with each message) must be fixed * during initialization of the logger * * Syslog provides its own formatting, so we turn off all formatting flags * of the LibUCW logger. You can override this manually by setting the @msgfmt * field of the log stream, but the result won't be nice. * * Syslog does not support timestamps with sub-second precision. ***/ /** * Create a log stream for logging to a selected syslog facility. * The @options are passed to openlog(). (Beware, due to limitations of the * syslog interface in libc, the @options are shared for all syslog streams * and they are applied when the first stream is created.) **/ struct log_stream *log_new_syslog(const char *facility, int options); /** * Verify that a facility of the given name exists. Return 1 if it does, 0 otherwise. **/ int log_syslog_facility_exists(const char *facility); /*** * === Configuring log streams * * If you use the LibUCW mechanism for parsing config files, you can let your * user configure arbitrary log streams in the Logging section of the config file * (see examples in the default config file). LibUCW automatically verifies that * the configuration is consistent (this is performed in the commit hook of the * config section), but it opens the streams only upon request. The following * functions can be used to control that. ***/ /** Open a log stream configured under the specified name and increase its use count. **/ struct log_stream *log_new_configured(const char *name); /** Open a log stream configured under the specified name and use it as the default destination. **/ void log_configured(const char *name); /** * Verify that a stream called @name was configured. If it wasn't, return an error * message. This is intended to be used in configuration commit hooks. **/ char *log_check_configured(const char *name); #endif