ucw/log.h

   1 /*
   2  *      UCW Library -- Logging
   3  *
   4  *      (c) 1997--2009 Martin Mares <mj@ucw.cz>
   5  *      (c) 2008 Tomas Gavenciak <gavento@ucw.cz>
   6  *
   7  *      This software may be freely distributed and used according to the terms
   8  *      of the GNU Lesser General Public License.
   9  */
  10
  11 #ifndef _UCW_LOG_H_
  12 #define _UCW_LOG_H_
  13
  14 #include "ucw/clists.h"
  15
  16 /*** === Messages and streams ***/
  17
  18 /**
  19  * Inside the logging system, a log message is always represented by this structure.
  20  **/
  21 struct log_msg {
  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
  25   struct timeval *tv;
  26   uns flags;                            // Category and other flags as passed to msg()
  27   char *raw_msg;                        // Unformatted parts
  28   char *stime;
  29   char *sutime;
  30 };
  31
  32 /**
  33  * Each stream is represented by an instance of this structure.
  34  **/
  35 struct log_stream {
  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
  48 };
  49
  50 /**
  51  * Formatting flags specifying the format of the message passed to the handler.
  52  **/
  53 enum ls_fmt {
  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
  61 };
  62
  63 #define LSFMT_DEFAULT (LSFMT_LEVEL | LSFMT_TIME | LSFMT_TITLE | LSFMT_PID)      /** Default format **/
  64
  65 /**
  66  * General stream flags.
  67  **/
  68 enum ls_flag {
  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
  71 };
  72
  73 /***
  74  * === Message flags
  75  *
  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`).
  79  ***/
  80
  81 enum ls_flagbits {                      // Bit widths of groups
  82   LS_LEVEL_BITS =       8,
  83   LS_STRNUM_BITS =      16,
  84   LS_TYPE_BITS =        5,
  85   LS_CTRL_BITS =        3,
  86 };
  87
  88 enum ls_flagpos {                       // Bit positions of groups
  89   LS_LEVEL_POS =        0,
  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,
  93 };
  94
  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,
 100 };
 101
 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 **/
 107
 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 **/
 113
 114 #define LS_NUM_TYPES (1 << LS_TYPE_BITS)
 115
 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);
 118
 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);
 121
 122 /** Given a flag set, extract the message type ID and return its name. **/
 123 char *log_type_name(uns flags);
 124
 125 /*** === Operations on streams ***/
 126
 127 /**
 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.
 131  **/
 132 struct log_stream *log_new_stream(size_t size);
 133
 134 /**
 135  * Decrement the use count of a stream. If it becomes zero, close the stream,
 136  * free its memory, and unlink all its substreams.
 137  **/
 138 int log_close_stream(struct log_stream *ls);
 139
 140 /**
 141  * Get a new reference on an existing stream. For convenience, the return value is
 142  * equal to the argument @ls.
 143  **/
 144 static inline struct log_stream *log_ref_stream(struct log_stream *ls)
 145 {
 146   ls->use_count++;
 147   return ls;
 148 }
 149
 150 /**
 151  * Link a substream to a stream. The substream gains a reference, preventing
 152  * it from being freed until it is unlinked.
 153  **/
 154 void log_add_substream(struct log_stream *where, struct log_stream *what);
 155
 156 /**
 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.
 160  **/
 161 int log_rm_substream(struct log_stream *where, struct log_stream *what);
 162
 163 /**
 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.
 166  **/
 167 void log_set_format(struct log_stream *ls, uns mask, uns data);
 168
 169 /**
 170  * Find a stream by its registration number (in the format of logging flags).
 171  * Returns NULL if there is no such stream.
 172  **/
 173 struct log_stream *log_stream_by_flags(uns flags);
 174
 175 /** Return a pointer to the default stream (stream #0). **/
 176 static inline struct log_stream *log_default_stream(void)
 177 {
 178   return log_stream_by_flags(0);
 179 }
 180
 181 /**
 182  * Close all open streams, un-initialize the module, free all memory and
 183  * reset the logging mechanism to use stderr only.
 184  **/
 185 void log_close_all(void);
 186
 187 /***
 188  * === Logging to files
 189  *
 190  * All log files are open in append mode, which guarantees atomicity of write()
 191  * even in multi-threaded programs.
 192  ***/
 193
 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. **/
 196
 197 /**
 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
 201  * can be nested.
 202  **/
 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. **/
 206
 207 /***
 208  * === Logging to syslog
 209  *
 210  * This log stream uses the libc interface to the system logging daemon (`syslogd`).
 211  * This interface has several limitations:
 212  *
 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.
 223  ***/
 224
 225 /**
 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.)
 230  **/
 231 struct log_stream *log_new_syslog(const char *facility, int options);
 232
 233 /**
 234  * Verify that a facility of the given name exists. Return 1 if it does, 0 otherwise.
 235  **/
 236 int log_syslog_facility_exists(const char *facility);
 237
 238 /***
 239  * === Configuring log streams
 240  *
 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.
 247  ***/
 248
 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);
 251
 252 /** Open a log stream configured under the specified name and use it as the default destination. **/
 253 void log_configured(const char *name);
 254
 255 /**
 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.
 258  **/
 259 char *log_check_configured(const char *name);
 260
 261 #endif