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   uns flags;                            // Category and other flags as passed to msg()
  26   char *raw_msg;                        // Unformatted parts
  27   char *stime;
  28   char *sutime;
  29 };
  30
  31 /**
  32  * Each stream is represented by an instance of this structure.
  33  **/
  34 struct log_stream {
  35   char *name;                           // Optional name, allocated by the user (or constructor)
  36   int regnum;                           // Stream number, already encoded by LS_SET_STRNUM(); -1 if closed
  37   uns levels;                           // Bitmask of accepted severity levels (default: all)
  38   uns msgfmt;                           // Formatting flags (LSFMT_xxx)
  39   uns use_count;                        // Number of references to the stream
  40   int (*filter)(struct log_stream* ls, struct log_msg *m);      // Filter function, return non-zero to discard the message
  41   clist substreams;                     // Pass the message to these streams (simple_list of pointers)
  42   int (*handler)(struct log_stream *ls, struct log_msg *m);     // Called to commit the message
  43   void (*close)(struct log_stream* ls); // Called upon log_close_stream()
  44   // Private data of the handler follow
  45 };
  46
  47 /**
  48  * Formatting flags specifying the format of the message passed to the handler.
  49  **/
  50 enum ls_fmt {
  51   LSFMT_LEVEL =         1,              // severity level (one letter) */
  52   LSFMT_TIME =          2,              // date and time (YYYY-mm-dd HH:MM:SS) */
  53   LSFMT_USEC =          4,              // also micro-seconds */
  54   LSFMT_TITLE =         8,              // program title (log_title) */
  55   LSFMT_PID =           16,             // program PID (log_pid) */
  56   LSFMT_LOGNAME =       32,             // name of the log_stream */
  57 };
  58
  59 #define LSFMT_DEFAULT (LSFMT_LEVEL | LSFMT_TIME)        /** Default format **/
  60
  61 // Return the letter associated with a given severity level
  62 #define LS_LEVEL_LETTER(level) ("DIiWwEe!###"[( level )])
  63
  64 /***
  65  * === Message flags
  66  *
  67  * The @flags parameter of msg() is divided to several groups of bits (from the LSB):
  68  * message severity level (`L_xxx`), destination stream, message type [currently unused]
  69  * and control bits (e.g., `L_SIGHANDLER`).
  70  ***/
  71
  72 enum ls_flagbits {                      // Bit widths of groups
  73   LS_LEVEL_BITS =       8,
  74   LS_STRNUM_BITS =      16,
  75   LS_TYPE_BITS =        5,
  76   LS_CTRL_BITS =        3,
  77 };
  78
  79 enum ls_flagpos {                       // Bit positions of groups
  80   LS_LEVEL_POS =        0,
  81   LS_STRNUM_POS =       LS_LEVEL_POS + LS_LEVEL_BITS,
  82   LS_TYPE_POS =         LS_STRNUM_POS + LS_STRNUM_BITS,
  83   LS_CTRL_POS =         LS_TYPE_POS + LS_TYPE_BITS,
  84 };
  85
  86 enum ls_flagmasks {                     // Bit masks of groups
  87   LS_LEVEL_MASK =       ((1 << LS_LEVEL_BITS) - 1) << LS_LEVEL_POS,
  88   LS_STRNUM_MASK =      ((1 << LS_STRNUM_BITS) - 1) << LS_STRNUM_POS,
  89   LS_TYPE_MASK =        ((1 << LS_TYPE_BITS) - 1) << LS_TYPE_POS,
  90   LS_CTRL_MASK =        ((1 << LS_CTRL_BITS) - 1) << LS_CTRL_POS,
  91 };
  92
  93 // "Get" macros (break flags to parts)
  94 #define LS_GET_LEVEL(flags)     (((flags) & LS_LEVEL_MASK) >> LS_LEVEL_POS)     /** Extract severity level **/
  95 #define LS_GET_STRNUM(flags)    (((flags) & LS_STRNUM_MASK) >> LS_STRNUM_POS)   /** Extract stream number **/
  96 #define LS_GET_TYPE(flags)      (((flags) & LS_TYPE_MASK) >> LS_TYPE_POS)       /** Extract message type **/
  97 #define LS_GET_CTRL(flags)      (((flags) & LS_CTRL_MASK) >> LS_CTRL_POS)       /** Extract control bits **/
  98
  99 // "Set" macros (parts to flags)
 100 #define LS_SET_LEVEL(level)     ((level) << LS_LEVEL_POS)                       /** Convert severity level to flags **/
 101 #define LS_SET_STRNUM(strnum)   ((strnum) << LS_STRNUM_POS)                     /** Convert stream number to flags **/
 102 #define LS_SET_TYPE(type)       ((type) << LS_TYPE_POS)                         /** Convert message type to flags **/
 103 #define LS_SET_CTRL(ctrl)       ((ctrl) << LS_CTRL_POS)                         /** Convert control bits to flags **/
 104
 105 /*** === Operations on streams ***/
 106
 107 /**
 108  * Allocate a new log stream with no handler and an empty substream list.
 109  * Since struct log_stream is followed by private data, @size bytes of memory are allocated
 110  * for the whole structure. See below for functions creating specific stream types.
 111  **/
 112 struct log_stream *log_new_stream(size_t size);
 113
 114 /**
 115  * Decrement the use count of a stream. If it becomes zero, close the stream,
 116  * free its memory, and unlink all its substreams.
 117  **/
 118 int log_close_stream(struct log_stream *ls);
 119
 120 /**
 121  * Get a new reference on an existing stream. For convenience, the return value is
 122  * equal to the argument @ls.
 123  **/
 124 static inline struct log_stream *log_ref_stream(struct log_stream *ls)
 125 {
 126   ls->use_count++;
 127   return ls;
 128 }
 129
 130 /**
 131  * Link a substream to a stream. The substream gains a reference.
 132  **/
 133 void log_add_substream(struct log_stream *where, struct log_stream *what);
 134
 135 /**
 136  * Unlink all occurrences of a substream @what from stream @where. Each
 137  * occurrence loses a reference. If @what is NULL, all substreams are unlinked.
 138  * Returns the number of unlinked substreams.
 139  **/
 140 int log_rm_substream(struct log_stream *where, struct log_stream *what);
 141
 142 /**
 143  * Set formatting flags of a given stream and all its substreams. The flags are
 144  * AND'ed with @mask and OR'ed with @data.
 145  **/
 146 void log_set_format(struct log_stream *ls, uns mask, uns data);
 147
 148 /**
 149  * Find a stream by its registration number (in the format of logging flags).
 150  * Returns NULL if there is no such stream.
 151  **/
 152 struct log_stream *log_stream_by_flags(uns flags);
 153
 154 /**
 155  * Return a pointer to the default stream (stream #0).
 156  **/
 157 static inline struct log_stream *log_default_stream(void)
 158 {
 159   return log_stream_by_flags(0);
 160 }
 161
 162 /**
 163  * Close all open streams, un-initialize the module, free all memory and
 164  * reset the logging mechanism to use stderr only.
 165  **/
 166 void log_close_all(void);
 167
 168 /***
 169  * === Logging to files
 170  *
 171  * All log files are open in append mode, which guarantees atomicity of write()
 172  * even in multi-threaded programs.
 173  ***/
 174
 175 struct log_stream *log_new_file(const char *path);              /** Create a stream bound to a log file. **/
 176 struct log_stream *log_new_fd(int fd);                          /** Create a stream bound to a file descriptor. **/
 177
 178 /**
 179  * When a time-based name of the log file changes, the logger switches to a new
 180  * log file automatically. This can be sometimes inconvenient, so you can use
 181  * this function to disable the automatic switches. The calls to this function
 182  * can be nested.
 183  **/
 184 void log_switch_disable(void);
 185 void log_switch_enable(void);           /** Negate the effect of log_switch_disable(). **/
 186 int log_switch(void);                   /** Switch log files manually. **/
 187
 188 /***
 189  * === Logging to syslog
 190  *
 191  * This log stream uses the libc interface to the system logging daemon (`syslogd`).
 192  * As syslog serverities differ from our scheme, they are translated; if you
 193  * are interested in details, search for syslog_level().
 194  *
 195  * Syslog also provides its own timestamps, so we turn off all formatting
 196  * of the LibUCW logger.
 197  ***/
 198
 199 /**
 200  * Create a log stream for logging to a selected syslog facility.
 201  * The @name is an optional prefix of the messages.
 202  **/
 203 struct log_stream *log_new_syslog(int facility, const char *name);
 204
 205 #endif