X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Flog.h;h=f2d99a0729d19e5ff79fdd06a26946743654d8d8;hb=521609b4721376161eabe89c9431aa221e87e263;hp=b5383cdf421c7f6982f26609f05c48c7cd1ffbfd;hpb=220a6551622b6c87b26450a3ca4fe48c1acfce95;p=libucw.git

diff --git a/ucw/log.h b/ucw/log.h
index b5383cdf..f2d99a07 100644
--- a/ucw/log.h
+++ b/ucw/log.h
@@ -22,6 +22,7 @@ struct log_msg {
   char *m;				// The formatted message itself, ending with \n\0
   int m_len;				// Length without the \0
   struct tm *tm;			// Current time
+  struct timeval *tv;
   uns flags;				// Category and other flags as passed to msg()
   char *raw_msg;			// Unformatted parts
   char *stime;
@@ -35,12 +36,15 @@ 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 types;				// Bitmask of accepted message types (default: all)
   uns msgfmt;				// Formatting flags (LSFMT_xxx)
   uns use_count;			// Number of references to the stream
+  uns 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
 };
 
@@ -54,18 +58,24 @@ enum ls_fmt {
   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]
+ * message severity level (`L_xxx`), destination stream, message type
  * and control bits (e.g., `L_SIGHANDLER`).
  ***/
 
@@ -102,6 +112,17 @@ enum ls_flagmasks {			// Bit masks of groups
 #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(uns flags);
+
 /*** === Operations on streams ***/
 
 /**
@@ -128,7 +149,8 @@ static inline struct log_stream *log_ref_stream(struct log_stream *ls)
 }
 
 /**
- * Link a substream to a stream. The substream gains a reference.
+ * Link a substream to a stream. The substream gains a reference, preventing
+ * it from being freed until it is unlinked.
  **/
 void log_add_substream(struct log_stream *where, struct log_stream *what);
 
@@ -151,9 +173,7 @@ void log_set_format(struct log_stream *ls, uns mask, uns data);
  **/
 struct log_stream *log_stream_by_flags(uns 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);
@@ -172,8 +192,14 @@ void log_close_all(void);
  * 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, uns flags);	/** Create a stream bound to a log file. See `FF_xxx` for @flags. **/
+struct log_stream *log_new_fd(int fd, uns 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
@@ -189,17 +215,54 @@ int log_switch(void);			/** Switch log files manually. **/
  * === 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.
+ **/
+int log_syslog_facility_exists(const char *facility);
+
+/***
+ * === Configuring log streams
+ *
+ * If you use the LibUCW mechanism for parsing config files, you can let your
+ * user configure arbitrary log streams in the Logging section of the config file
+ * (see examples in the default config file). LibUCW automatically verifies that
+ * the configuration is consistent (this is performed in the commit hook of the
+ * config section), but it opens the streams only upon request. The following
+ * functions can be used to control that.
+ ***/
+
+/** 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.
  **/
-struct log_stream *log_new_syslog(int facility, const char *name);
+char *log_check_configured(const char *name);
 
 #endif