X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Flog.h;h=6ff2d4e56b8d82669dfbadf4848c0691cf3227de;hb=156301aa8c7fd24d49ed27cfbd1afc10ccb7bc58;hp=f7baf629a33d146c3679787ca89a0bcec35118e0;hpb=d22dba5a3ad6cd0e0be4c07527218c6b48fd5bd3;p=libucw.git diff --git a/ucw/log.h b/ucw/log.h index f7baf629..6ff2d4e5 100644 --- a/ucw/log.h +++ b/ucw/log.h @@ -11,7 +11,32 @@ #ifndef _UCW_LOG_H_ #define _UCW_LOG_H_ -#include "ucw/clists.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_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 ***/ @@ -22,10 +47,13 @@ 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 - uns flags; // Category and other flags as passed to msg() + 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) }; /** @@ -34,13 +62,16 @@ struct log_msg { 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 - uns levels; // Bitmask of accepted severity levels (default: all) - uns msgfmt; // Formatting flags (LSFMT_xxx) - uns use_count; // Number of references to the stream + 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 + 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 }; @@ -54,18 +85,24 @@ enum ls_fmt { 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) /** Default format **/ +#define LSFMT_DEFAULT (LSFMT_LEVEL | LSFMT_TIME | LSFMT_TITLE | LSFMT_PID) /** Default format **/ -// Return the letter associated with a given severity level -#define LS_LEVEL_LETTER(level) ("DIiWwEe!###"[( level )]) +/** + * 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 msg() is divided to several groups of bits (from the LSB): - * message severity level (`L_xxx`), destination stream, message type [currently unused] + * 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`). ***/ @@ -102,6 +139,17 @@ enum ls_flagmasks { // Bit masks of groups #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 ***/ /** @@ -144,28 +192,46 @@ 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, uns mask, uns 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(uns flags); +struct log_stream *log_stream_by_flags(uint flags); -/** - * Return a pointer to the default stream (stream #0). - **/ +/** 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 * @@ -173,8 +239,14 @@ void log_close_all(void); * even in multi-threaded programs. ***/ -struct log_stream *log_new_file(const char *path); /** Create a stream bound to a log file. **/ -struct log_stream *log_new_fd(int fd); /** Create a stream bound to a file descriptor. **/ +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 @@ -190,17 +262,54 @@ int log_switch(void); /** Switch log files manually. **/ * === Logging to syslog * * This log stream uses the libc interface to the system logging daemon (`syslogd`). - * As syslog serverities differ from our scheme, they are translated; if you - * are interested in details, search for syslog_level(). + * This interface has several limitations: * - * Syslog also provides its own timestamps, so we turn off all formatting - * of the LibUCW logger. + * * 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 @name is an optional prefix of the messages. + * 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. **/ -struct log_stream *log_new_syslog(int facility, const char *name); +char *log_check_configured(const char *name); #endif