/*
* UCW Library -- Logging
*
- * (c) 1997--2009 Martin Mares <mj@ucw.cz>
+ * (c) 1997--2015 Martin Mares <mj@ucw.cz>
* (c) 2008 Tomas Gavenciak <gavento@ucw.cz>
*
* This software may be freely distributed and used according to the terms
#ifndef _UCW_LOG_H_
#define _UCW_LOG_H_
-#include "ucw/clists.h"
+#include <ucw/clists.h>
+
+#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_drop_stderr ucw_log_drop_stderr
+#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 ***/
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)
};
/**
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
};
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 <<basics:msg()>> 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`).
***/
#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 ***/
/**
* 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 <<basics:log_file()>> 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
*
* 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
void log_switch_enable(void); /** Negate the effect of log_switch_disable(). **/
int log_switch(void); /** Switch log files manually. **/
+/**
+ * Drop stderr if it is not already redirected to a log file.
+ * This is usually needed in daemons to make sure that the original
+ * stderr does not stay open (stdin and stdout are dropped by our
+ * <<daemon:,daemon setup functions>> automatically). More specifically,
+ * it makes stderr a clone of stdout.
+ **/
+void log_drop_stderr(void);
+
/***
* === 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.
**/
-struct log_stream *log_new_syslog(int facility, const char *name);
+int log_syslog_facility_exists(const char *facility);
/***
* === Configuring log streams
/** 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.