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 /* user de/allocated program/process name for use in the logsystem */
  17 extern char *ls_title;
  18
  19 struct log_msg
  20 {
  21   char *m;                              // The formatted message itself, ending with \n\0
  22   int m_len;                            // Length without the \0
  23   struct tm *tm;                        // Current time
  24   uns flags;                            // Category and other flags as passed to msg()
  25   char *raw_msg;                        // Unformatted parts
  26   char *stime;
  27   char *sutime;
  28 };
  29
  30 struct log_stream
  31 {
  32   char *name;                           // Optional name, allocated by the user (or constructor)
  33   int regnum;                           // Stream number, already encoded by LS_SET_STRNUM(); -1 if closed
  34   uns levels;                           // Bitmask of accepted severity levels
  35   uns msgfmt;                           // Formatting flags (LSFMT_xxx)
  36   uns use_count;                        // Number of references to the stream
  37   int (*filter)(struct log_stream* ls, struct log_msg *m);      // Filter function, return non-zero to discard the message
  38   struct clist substreams;              // Pass the message to these streams (simple_list of pointers)
  39   int (*handler)(struct log_stream *ls, struct log_msg *m);     // Called to commit the message
  40   void (*close)(struct log_stream* ls); // Called upon log_close_stream()
  41   int idata;                            // Private data of the handler
  42   void *pdata;
  43   uns udata;
  44 };
  45
  46 /* the default logger */
  47 extern struct log_stream log_stream_default;
  48 #define LOG_STREAM_DEFAULT &log_stream_default
  49
  50 /* A message is processed as follows:
  51  *  1. Discard if message level not in levels
  52  *  2. Run filter (if any), discard if ret. nonzero
  53  *  3. Pass the message to all log_streams in substreams
  54  *  4. Format the message informaion acc. to msgfmt
  55  *  5. Run the handler
  56  */
  57
  58 /* log header verbosity specifying message passed to handler */
  59 enum ls_fmt
  60 {
  61   LSFMT_LEVEL=1,       /* log severity level (one letter) */
  62   LSFMT_TIME=2,        /* log time (date-seconds) */
  63   LSFMT_USEC=4,        /* log also micro-seconds */
  64   LSFMT_TITLE=8,       /* log program title (global string) */
  65   LSFMT_PID=16,        /* log program PID */
  66   LSFMT_LOGNAME=32,    /* log log_stream name */
  67   LSFMT_NONE=0,
  68   LSFMT_FULL=LSFMT_LEVEL+LSFMT_TIME+LSFMT_USEC+LSFMT_TITLE+LSFMT_PID+LSFMT_LOGNAME,
  69   LSFMT_DEFAULT=LSFMT_LEVEL+LSFMT_TIME
  70 };
  71
  72 /* Mask of containing all existing levels. */
  73 #define LS_ALL_LEVELS 0xfff
  74
  75 // return the letter associated with the severity level
  76 #define LS_LEVEL_LETTER(level) ("DIiWwEe!###"[( level )])
  77
  78 ///// Macros for extracting parts of the flags parameter
  79 // The division of the flags parameter is decided only here
  80 // The current division is (for 32 bit flags):
  81 // MSB <5 bits: any internal log flags> <8 bits: "user" flags> <10 bits: stream number>
  82 //     <8 bits: severity level> LSB
  83
  84 // Bits per section
  85 enum ls_flagbits {
  86   LS_LEVEL_BITS    = 8,
  87   LS_STRNUM_BITS   = 16,
  88   LS_FLAGS_BITS    = 5,
  89   LS_INTERNAL_BITS = 4,
  90 };
  91
  92 // Section shifts
  93 enum ls_flagpos {
  94   LS_LEVEL_POS     = 0,
  95   LS_STRNUM_POS    = LS_LEVEL_POS + LS_LEVEL_BITS,
  96   LS_FLAGS_POS     = LS_STRNUM_POS + LS_STRNUM_BITS,
  97   LS_INTERNAL_POS  = LS_FLAGS_POS + LS_FLAGS_BITS,
  98 };
  99
 100 // Bitmasks
 101 enum ls_flagmasks {
 102   LS_LEVEL_MASK    = (( 1 << LS_LEVEL_BITS ) - 1 ) << LS_LEVEL_POS,
 103   LS_STRNUM_MASK   = (( 1 << LS_STRNUM_BITS ) - 1 ) << LS_STRNUM_POS,
 104   LS_FLAGS_MASK    = (( 1 << LS_FLAGS_BITS ) - 1 ) << LS_FLAGS_POS,
 105   LS_INTERNAL_MASK = (( 1 << LS_INTERNAL_BITS ) - 1 ) << LS_INTERNAL_POS,
 106 };
 107
 108 // "Get" macros (break flags to parts)
 109 #define LS_GET_LEVEL(flags)     ((( flags ) & LS_LEVEL_MASK ) >> LS_LEVEL_POS )
 110 #define LS_GET_STRNUM(flags)    ((( flags ) & LS_STRNUM_MASK ) >> LS_STRNUM_POS )
 111 #define LS_GET_FLAGS(flags)     ((( flags ) & LS_FLAGS_MASK ) >> LS_FLAGS_POS )
 112 #define LS_GET_INTERNAL(flags)  ((( flags ) & LS_INTERNAL_MASK ) >> LS_INTERNAL_POS )
 113
 114 // "Set" macros (parts to flags)
 115 #define LS_SET_LEVEL(level)     (( level ) << LS_LEVEL_POS )
 116 #define LS_SET_STRNUM(strnum)   (( strnum ) << LS_STRNUM_POS )
 117 #define LS_SET_FLAGS(flags)     (( flags ) << LS_FLAGS_POS )
 118 #define LS_SET_INTERNAL(intern) (( intern ) << LS_INTERNAL_POS )
 119
 120 // Internal flags of the logsystem
 121 // Avoid operations that are unsafe in signal handlers
 122 #define LSFLAG_SIGHANDLER LS_SET_INTERNAL(0x001)
 123
 124 // The module is initialized when a first stream is created.
 125 // Before that only the default stream exists.
 126
 127 /* Return pointer a new (xmalloc()-ated) stream with no handler and an empty substream list. */
 128 struct log_stream *log_new_stream(void);
 129
 130 /* Close and xfree() given log_stream */
 131 /* Does not affect substreams */
 132 int log_close_stream(struct log_stream *ls);
 133
 134 /* Get a new reference on a stream */
 135 static inline struct log_stream *
 136 log_ref_stream(struct log_stream *ls)
 137 {
 138   ls->use_count++;
 139   return ls;
 140 }
 141
 142 /* close all open streams, un-initialize the module, free all memory,
 143  * use only ls_default_log */
 144 void log_close_all(void);
 145
 146 /* add a new substream, xmalloc()-ate a new simp_node */
 147 void log_add_substream(struct log_stream *where, struct log_stream *what);
 148
 149 /* remove all occurences of a substream, free() the simp_node */
 150 /* return number of deleted entries */
 151 int log_rm_substream(struct log_stream *where, struct log_stream *what);
 152
 153 /* get a stream by its number (regnum) */
 154 /* returns NULL for free numbers */
 155 /* defaults to ls_default_stream for 0 when stream number 0 not set */
 156 struct log_stream *log_stream_by_flags(uns flags);
 157
 158 /* process a message (string) (INTERNAL) */
 159 /* depth prevents undetected looping */
 160 /* returns 1 in case of loop detection or other fatal error
 161  *         0 otherwise */
 162 int log_pass_msg(int depth, struct log_stream *ls, struct log_msg *m);
 163
 164 /* Define an array (growing buffer) for pointers to log_streams. */
 165 #define GBUF_TYPE struct log_stream*
 166 #define GBUF_PREFIX(x) lsbuf_##x
 167 #include "ucw/gbuf.h"
 168
 169 extern struct lsbuf_t log_streams;
 170 extern int log_streams_after;
 171
 172 /********* Individual handler types (constructors, handlers, destructors) */
 173
 174 /**** standard (filedes) files */
 175
 176 // NOTE:
 177 // under unix, for ordinary files open in append mode, the writes
 178 // are atomic (unless you meet the quota or other bad things happen),
 179 // so using a single log_stream is thread-safe and the file can be shared
 180 // among multiple processes
 181
 182 /* assign log to a file descriptor */
 183 /* initialize with the default formatting, does NOT close the descriptor */
 184 struct log_stream *log_new_fd(int fd);
 185
 186 /* open() a file (append mode) */
 187 /* initialize with the default formatting */
 188 struct log_stream *log_new_file(const char *path);
 189
 190
 191 /**** syslog */
 192
 193 // NOTE:
 194 // The syslog uses a bit different severity levels, for details, see
 195 // ls_syslog_convert_level().
 196 // syslog also prepends it's own time and severity info, so the default
 197 // messaging passes only clean message
 198
 199 /* assign log to a syslog facility */
 200 /* initialize with no formatting (syslog adds these inforamtion) */
 201 /* name is optional prefix (NULL for none) */
 202 struct log_stream *log_new_syslog(int facility, const char *name);
 203
 204 #endif