2 * UCW Library -- Logging
4 * (c) 1997--2009 Martin Mares <mj@ucw.cz>
5 * (c) 2008 Tomas Gavenciak <gavento@ucw.cz>
7 * This software may be freely distributed and used according to the terms
8 * of the GNU Lesser General Public License.
14 #include "ucw/clists.h"
16 /* user de/allocated program/process name for use in the logsystem */
17 extern char *ls_title;
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
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 // Private data of the handler follow
44 /* the default logger */
45 extern struct log_stream log_stream_default;
47 /* A message is processed as follows:
48 * 1. Discard if message level not in levels
49 * 2. Run filter (if any), discard if ret. nonzero
50 * 3. Pass the message to all log_streams in substreams
51 * 4. Format the message informaion acc. to msgfmt
55 /* log header verbosity specifying message passed to handler */
58 LSFMT_LEVEL=1, /* log severity level (one letter) */
59 LSFMT_TIME=2, /* log time (date-seconds) */
60 LSFMT_USEC=4, /* log also micro-seconds */
61 LSFMT_TITLE=8, /* log program title (global string) */
62 LSFMT_PID=16, /* log program PID */
63 LSFMT_LOGNAME=32, /* log log_stream name */
65 LSFMT_FULL=LSFMT_LEVEL+LSFMT_TIME+LSFMT_USEC+LSFMT_TITLE+LSFMT_PID+LSFMT_LOGNAME,
66 LSFMT_DEFAULT=LSFMT_LEVEL+LSFMT_TIME
69 /* Mask of containing all existing levels. */
70 #define LS_ALL_LEVELS 0xfff
72 // return the letter associated with the severity level
73 #define LS_LEVEL_LETTER(level) ("DIiWwEe!###"[( level )])
75 ///// Macros for extracting parts of the flags parameter
76 // The division of the flags parameter is decided only here
77 // The current division is (for 32 bit flags):
78 // MSB <5 bits: any internal log flags> <8 bits: "user" flags> <10 bits: stream number>
79 // <8 bits: severity level> LSB
92 LS_STRNUM_POS = LS_LEVEL_POS + LS_LEVEL_BITS,
93 LS_FLAGS_POS = LS_STRNUM_POS + LS_STRNUM_BITS,
94 LS_INTERNAL_POS = LS_FLAGS_POS + LS_FLAGS_BITS,
99 LS_LEVEL_MASK = (( 1 << LS_LEVEL_BITS ) - 1 ) << LS_LEVEL_POS,
100 LS_STRNUM_MASK = (( 1 << LS_STRNUM_BITS ) - 1 ) << LS_STRNUM_POS,
101 LS_FLAGS_MASK = (( 1 << LS_FLAGS_BITS ) - 1 ) << LS_FLAGS_POS,
102 LS_INTERNAL_MASK = (( 1 << LS_INTERNAL_BITS ) - 1 ) << LS_INTERNAL_POS,
105 // "Get" macros (break flags to parts)
106 #define LS_GET_LEVEL(flags) ((( flags ) & LS_LEVEL_MASK ) >> LS_LEVEL_POS )
107 #define LS_GET_STRNUM(flags) ((( flags ) & LS_STRNUM_MASK ) >> LS_STRNUM_POS )
108 #define LS_GET_FLAGS(flags) ((( flags ) & LS_FLAGS_MASK ) >> LS_FLAGS_POS )
109 #define LS_GET_INTERNAL(flags) ((( flags ) & LS_INTERNAL_MASK ) >> LS_INTERNAL_POS )
111 // "Set" macros (parts to flags)
112 #define LS_SET_LEVEL(level) (( level ) << LS_LEVEL_POS )
113 #define LS_SET_STRNUM(strnum) (( strnum ) << LS_STRNUM_POS )
114 #define LS_SET_FLAGS(flags) (( flags ) << LS_FLAGS_POS )
115 #define LS_SET_INTERNAL(intern) (( intern ) << LS_INTERNAL_POS )
117 // Internal flags of the logsystem
118 // Avoid operations that are unsafe in signal handlers
119 #define LSFLAG_SIGHANDLER LS_SET_INTERNAL(0x001)
121 // The module is initialized when a first stream is created.
122 // Before that only the default stream exists.
124 /* Return pointer a new (xmalloc()-ated) stream with no handler and an empty substream list.
125 * Since struct log_stream is followed by private data, @size bytes of memory are allocated
126 * for the whole structure. */
127 struct log_stream *log_new_stream(size_t size);
129 /* Close and xfree() given log_stream */
130 /* Does not affect substreams */
131 int log_close_stream(struct log_stream *ls);
133 /* Get a new reference on a stream */
134 static inline struct log_stream *
135 log_ref_stream(struct log_stream *ls)
141 /* close all open streams, un-initialize the module, free all memory,
142 * use only ls_default_log */
143 void log_close_all(void);
145 /* add a new substream, xmalloc()-ate a new simp_node */
146 void log_add_substream(struct log_stream *where, struct log_stream *what);
148 /* remove all occurences of a substream, free() the simp_node */
149 /* return number of deleted entries */
150 int log_rm_substream(struct log_stream *where, struct log_stream *what);
152 /* Set formatting flags of a given stream and all its substreams. The flags are
153 * ANDed with @mask and ORed with @data. */
154 void log_set_format(struct log_stream *ls, uns mask, uns data);
156 /* get a stream by its number (regnum) */
157 /* returns NULL for free numbers */
158 /* defaults to ls_default_stream for 0 when stream number 0 not set */
159 struct log_stream *log_stream_by_flags(uns flags);
161 static inline struct log_stream *log_default_stream(void)
163 return log_stream_by_flags(0);
166 /* process a message (string) (INTERNAL) */
167 /* depth prevents undetected looping */
168 /* returns 1 in case of loop detection or other fatal error
170 int log_pass_msg(int depth, struct log_stream *ls, struct log_msg *m);
172 /* Define an array (growing buffer) for pointers to log_streams. */
173 #define GBUF_TYPE struct log_stream*
174 #define GBUF_PREFIX(x) lsbuf_##x
175 #include "ucw/gbuf.h"
177 extern struct lsbuf_t log_streams;
178 extern int log_streams_after;
180 /********* Individual handler types (constructors, handlers, destructors) */
182 /**** standard (filedes) files */
185 // under unix, for ordinary files open in append mode, the writes
186 // are atomic (unless you meet the quota or other bad things happen),
187 // so using a single log_stream is thread-safe and the file can be shared
188 // among multiple processes
190 /* assign log to a file descriptor */
191 /* initialize with the default formatting, does NOT close the descriptor */
192 struct log_stream *log_new_fd(int fd);
194 /* open() a file (append mode) */
195 /* initialize with the default formatting */
196 struct log_stream *log_new_file(const char *path);
198 /* If the log name contains metacharacters for date and time, we switch the logs
199 * automatically whenever the name changes. You can disable it and switch explicitly. */
200 void log_switch_disable(void);
201 void log_switch_enable(void);
202 int log_switch(void);
207 // The syslog uses a bit different severity levels, for details, see
208 // ls_syslog_convert_level().
209 // syslog also prepends it's own time and severity info, so the default
210 // messaging passes only clean message
212 /* assign log to a syslog facility */
213 /* initialize with no formatting (syslog adds these inforamtion) */
214 /* name is optional prefix (NULL for none) */
215 struct log_stream *log_new_syslog(int facility, const char *name);