Logging: The first bits of documentation.

I have also introduced a documentation chapter for <ucw/lib.h>, but only
logging functions are described so far.

log_switch() and friends have been moved to <ucw/log.h>, they are used rarely.

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index 88e59d5d8dc11822ab29daafa2da0ad4bec87953..6ffeb12367919ecf13e7a2d2e01e115d6aff11ef 100644 (file)
--- a/ucw/doc/Makefile
+++ b/ucw/doc/Makefile
@@ -2,7 +2,7 @@
 
 DIRS+=ucw/doc
 
-UCW_DOCS=fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode prime binsearch heap binheap compress sort hashtable
+UCW_DOCS=basics log fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode prime binsearch heap binheap compress sort hashtable
 UCW_INDEX=$(o)/ucw/doc/def_index.html
 UCW_DOCS_HTML=$(addprefix $(o)/ucw/doc/,$(addsuffix .html,$(UCW_DOCS)))
 

diff --git a/ucw/doc/basics.txt b/ucw/doc/basics.txt
new file mode 100644 (file)
index 0000000..4400a7d
--- /dev/null
+++ b/ucw/doc/basics.txt
@@ -0,0 +1,9 @@
+LibUCW Basics
+=============
+
+*Currently, only the logging functions are documented.*
+
+ucw/lib.h
+---------
+
+!!ucw/lib.h

diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt
index 2c69d6ae67569e7e027e8b9f09a3f135ab4c81ef..00935c3ec704766e35d9fde84963a4e91026e2ce 100644 (file)
--- a/ucw/doc/index.txt
+++ b/ucw/doc/index.txt
@@ -14,6 +14,8 @@ You can see the index of <<def_index:,documented definitions>>.
 
 Modules
 -------
+- <<basics:,Basics>>
+- <<log:,Logging>>
 - <<fastbuf:,Fastbufs>>
 - <<basecode:,Base64 and Base224 encoding>>
 - <<hash:,Hashing routines>>

diff --git a/ucw/doc/log.txt b/ucw/doc/log.txt
new file mode 100644 (file)
index 0000000..16ae1dc
--- /dev/null
+++ b/ucw/doc/log.txt
@@ -0,0 +1,4 @@
+Logging
+=======
+
+See <<basics:logging,Basics>> for the basic logging functions.

diff --git a/ucw/lib.h b/ucw/lib.h
index 8448eac5873af207f2a1e6b61321e4a3bc861811..c063e01658e3ccd377bb8549bb3eb32dc9cc2370 100644 (file)
--- a/ucw/lib.h
+++ b/ucw/lib.h
@@ -80,10 +80,13 @@
 #error This program requires the GNU C compiler.
 #endif
 
-/* Logging (more in <ucw/log.h>) */
+/***
+ * [[logging]]
+ *
+ * === Basic logging functions (see <<log:,Logging>> and <ucw/log.h> for more)
+ ***/
 
-enum log_levels
-{
+enum log_levels {                      /** The available log levels to pass to msg() and friends. **/
   L_DEBUG=0,                           // 'D' - Debugging
   L_INFO,                              // 'I' - Informational
   L_WARN,                              // 'W' - Warning
@@ -94,30 +97,32 @@ enum log_levels
   L_FATAL,                             // '!' - Fatal error
 };
 
-#define L_SIGHANDLER 0x80000000                /* Avoid operations that are unsafe in signal handlers */
-
-extern char *log_title;                        /* NULL - print no title, default is program name given to log_init() */
-extern int log_pid;                    /* 0 if shouldn't be logged */
-extern void (*log_die_hook)(void);     // FIXME
+#define L_SIGHANDLER 0x80000000                /** Avoid operations that are unsafe in signal handlers **/
 
+/**
+ * This is the basic printf-like function for logging a message.
+ * The @flags contain the log level and possibly other flag bits (like @L_SIGHANDLER).
+ **/
 void msg(uns flags, const char *fmt, ...) FORMAT_CHECK(printf,2,3);
-void vmsg(uns flags, const char *fmt, va_list args);
-void die(const char *, ...) NONRET FORMAT_CHECK(printf,1,2);
+void vmsg(uns flags, const char *fmt, va_list args);           /** A vararg version of msg(). **/
+void die(const char *, ...) NONRET FORMAT_CHECK(printf,1,2);   /** Log a fatal error message and exit the program. **/
 
-void log_init(const char *argv0);
-void log_file(const char *name);
-void log_fork(void);                   /* Call after fork() to update log_pid */
+extern char *log_title;                        /** An optional log message title. Set to program name by log_init(). **/
+extern int log_pid;                    /** An optional PID printed in each log message. Set to 0 if it shouldn't be logged. **/
+extern void (*log_die_hook)(void);     /** An optional function called just before die() exists. **/
 
-/* If the log name contains metacharacters for date and time, we switch the logs
- * automatically whenever the name changes. You can disable it and switch explicitly. */
-int log_switch(void);
-void log_switch_disable(void);
-void log_switch_enable(void);
+void log_init(const char *argv0);      /** Set @log_title to the program name extracted from @argv[0]. **/
+void log_fork(void);                   /** Call after fork() to update @log_pid. **/
+void log_file(const char *name);       /** Establish logging to the named file. Also redirect stderr there. **/
 
 void assert_failed(const char *assertion, const char *file, int line) NONRET;
 void assert_failed_noinfo(void) NONRET;
 
 #ifdef DEBUG_ASSERTS
+/**
+ * Check an assertion. If the condition @x is false, stop the program with a fatal error.
+ * These checks are compiled only when @DEBUG_ASSERTS is defined.
+ **/
 #define ASSERT(x) ({ if (unlikely(!(x))) assert_failed(#x, __FILE__, __LINE__); 1; })
 #else
 #define ASSERT(x) ({ if (__builtin_constant_p(x) && !(x)) assert_failed_noinfo(); 1; })
@@ -126,7 +131,7 @@ void assert_failed_noinfo(void) NONRET;
 #define COMPILE_ASSERT(name,x) typedef char _COMPILE_ASSERT_##name[!!(x)-1]
 
 #ifdef LOCAL_DEBUG
-#define DBG(x,y...) msg(L_DEBUG, x,##y)
+#define DBG(x,y...) msg(L_DEBUG, x,##y)        /** If @LOCAL_DEBUG is defined before including <ucw/lib.h>, log a debug message. Otherwise do nothing. **/
 #else
 #define DBG(x,y...) do { } while(0)
 #endif

diff --git a/ucw/log.h b/ucw/log.h
index bbecb0fce4c676ce33914797ec871bd2b3d90507..911e865fc9c6f71ed6a7139d46826f4654d583e7 100644 (file)
--- a/ucw/log.h
+++ b/ucw/log.h
@@ -195,6 +195,11 @@ struct log_stream *log_new_fd(int fd);
 /* initialize with the default formatting */
 struct log_stream *log_new_file(const char *path);
 
+/* If the log name contains metacharacters for date and time, we switch the logs
+ * automatically whenever the name changes. You can disable it and switch explicitly. */
+void log_switch_disable(void);
+void log_switch_enable(void);
+int log_switch(void);
 
 /**** syslog */