From d2de1962101b6af9eb2a5e79d18c5b326e90499f Mon Sep 17 00:00:00 2001 From: scottmk Date: Sun, 11 Oct 2009 18:39:16 +0000 Subject: [PATCH] Add doxygen-style comments to document macros, and an overview at the top. M include/opensrf/log.h git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1814 9efc2488-bf62-4759-914b-345cdb29e865 --- include/opensrf/log.h | 60 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 51 insertions(+), 9 deletions(-) diff --git a/include/opensrf/log.h b/include/opensrf/log.h index 16d72ed..71b0d60 100644 --- a/include/opensrf/log.h +++ b/include/opensrf/log.h @@ -4,6 +4,44 @@ /** @file log.h @brief Header for logging routines. + + The OSRF logging routines support five different levels of log messages, and route them + to any of three kinds of destinations. Utility routines are available to control various + details. + + The message levels are as follows: + + - OSRF_LOG_ERROR for error messages + - OSRF_LOG_WARNING for warning messages + - OSRF_LOG_INFO for informational messages + - OSRF_LOG_DEBUG for debug messages + - OSRF_LOG_INTERNAL for internal messages + + The application can set a message level so as to suppress some of the messages. + Each level includes the ones above it. For example, if the message level is set to + OSRF_LOG_INFO, then the logging routines will issue error messages, warning messages, and + informational messages, but suppress debug messages and internal messages. + + There are also activity messages, which are similar to informational messages, but can be + enabled or disabled separately. + + The messages may be written to standard error (the default), to a designated log file, or + to the Syslog (see man syslog). In the latter case, the application can specify a facility + number in order to control what Syslog does with the messages. The facility number for + activity numbers is controlled separately from that of the other message types. + + The messages are formatted like the following example: + + srfsh 2009-10-09 15:58:23 [DEBG:10530:socket_bundle.c:394:] removing socket 5 + + The message includes: + + -# An application name + -# A time stamp + -# A tag indicating the message level + -# The file name and line number from whence the message was issued + -# An optional transaction id (not present in this example) + -# The message text, formatted using printf-style conventions */ #include @@ -18,17 +56,21 @@ extern "C" { #endif /* log levels */ -#define OSRF_LOG_ERROR 1 -#define OSRF_LOG_WARNING 2 -#define OSRF_LOG_INFO 3 -#define OSRF_LOG_DEBUG 4 -#define OSRF_LOG_INTERNAL 5 -#define OSRF_LOG_ACTIVITY -1 +#define OSRF_LOG_ERROR 1 /**< Level for error messages */ +#define OSRF_LOG_WARNING 2 /**< Level for warning messages */ +#define OSRF_LOG_INFO 3 /**< Level for informational messages */ +#define OSRF_LOG_DEBUG 4 /**< Level for debug messages */ +#define OSRF_LOG_INTERNAL 5 /**< Level for internal messages */ +#define OSRF_LOG_ACTIVITY -1 /**< Pseudo message level for activity messages */ -#define OSRF_LOG_TYPE_FILE 1 -#define OSRF_LOG_TYPE_SYSLOG 2 -#define OSRF_LOG_TYPE_STDERR 3 +#define OSRF_LOG_TYPE_FILE 1 /**< Direct messages to a log file */ +#define OSRF_LOG_TYPE_SYSLOG 2 /**< Direct messages to Syslog */ +#define OSRF_LOG_TYPE_STDERR 3 /**< Direct messages to standard error */ +/** + Convenience macro for passing source file name and line number + to the logging routines +*/ #define OSRF_LOG_MARK __FILE__, __LINE__ void osrfLogInit( int type, const char* appname, int maxlevel ); -- 2.43.2