[Opensrf-commits] r1813 - in trunk: include/opensrf src/libopensrf (scottmk)

svn at svn.open-ils.org svn at svn.open-ils.org
Sun Oct 11 13:31:07 EDT 2009


Author: scottmk
Date: 2009-10-11 13:31:03 -0400 (Sun, 11 Oct 2009)
New Revision: 1813

Modified:
   trunk/include/opensrf/log.h
   trunk/src/libopensrf/log.c
Log:
Add doxygen-style comments to document all functions and all variables
at file scope.

In log.h: remove some existing comments so that they won't override
the more complete comments in log.c.

M    include/opensrf/log.h
M    src/libopensrf/log.c


Modified: trunk/include/opensrf/log.h
===================================================================
--- trunk/include/opensrf/log.h	2009-10-11 03:43:19 UTC (rev 1812)
+++ trunk/include/opensrf/log.h	2009-10-11 17:31:03 UTC (rev 1813)
@@ -31,74 +31,52 @@
 
 #define OSRF_LOG_MARK __FILE__, __LINE__
 
-
-/* Initializes the logger. */
 void osrfLogInit( int type, const char* appname, int maxlevel );
 
-/** Sets the systlog facility for the regular logs */
 void osrfLogSetSyslogFacility( int facility );
 
-/** Sets the systlog facility for the activity logs */
 void osrfLogSetSyslogActFacility( int facility );
 
-/** Reroutes logged messages to standard error; */
-/** intended for development and debugging */
 void osrfLogToStderr( void );
 
-/** Undoes the effects of osrfLogToStderr() */
 void osrfRestoreLogType( void );
 
-/** Sets the log file to use if we're logging to a file */
 void osrfLogSetFile( const char* logfile );
 
-/* once we know which application we're running, call this method to
- * set the appname so log lines can include the app name */
 void osrfLogSetAppname( const char* appname );
 
-/** Set or Get the global log level.  Any log statements with a higher level
- * than "level" will not be logged */
 void osrfLogSetLevel( int loglevel );
+
 int osrfLogGetLevel( void );
 
-/* Log an error message */
 void osrfLogError( const char* file, int line, const char* msg, ... );
 
-/* Log a warning message */
 void osrfLogWarning( const char* file, int line, const char* msg, ... );
 
-/* log an info message */
 void osrfLogInfo( const char* file, int line, const char* msg, ... );
 
-/* Log a debug message */
 void osrfLogDebug( const char* file, int line, const char* msg, ... );
 
-/* Log an internal debug message */
 void osrfLogInternal( const char* file, int line, const char* msg, ... );
 
-/* Log an activity message */
 void osrfLogActivity( const char* file, int line, const char* msg, ... );
 
 void osrfLogCleanup( void );
 
 void osrfLogClearXid( void );
-/**
- * Set the log XID.  This only sets the xid if we are not the origin client 
- */
+
 void osrfLogSetXid(char* xid);
-/**
- * Set the log XID regardless of whether we are the origin client
- */
+
 void osrfLogForceXid(char* xid);
+
 void osrfLogMkXid( void );
+
 void osrfLogSetIsClient(int is);
+
 const char* osrfLogGetXid( void );
 
-/* sets the activity flag */
 void osrfLogSetActivityEnabled( int enabled );
 
-/* returns the int representation of the log facility based on the facility name
- * if the facility name is invalid, LOG_LOCAL0 is returned 
- */
 int osrfLogFacilityToInt( const char* facility );
 
 #ifdef __cplusplus

Modified: trunk/src/libopensrf/log.c
===================================================================
--- trunk/src/libopensrf/log.c	2009-10-11 03:43:19 UTC (rev 1812)
+++ trunk/src/libopensrf/log.c	2009-10-11 17:31:03 UTC (rev 1813)
@@ -5,19 +5,37 @@
 
 #include <opensrf/log.h>
 
+/** Pseudo-log type indicating that no previous log type was defined.
+	See also _prevLogType. */
 #define OSRF_NO_LOG_TYPE -1
 
+/** Stores a log type during temporary redirections to standard error. */
 static int _prevLogType             = OSRF_NO_LOG_TYPE;
+/** Defines the destination of log messages: standard error, a log file, or Syslog. */
 static int _osrfLogType				= OSRF_LOG_TYPE_STDERR;
+/** Defines the Syslog facility number used for log messages other than activity messages.
+	Defaults to LOG_LOCAL0. */
 static int _osrfLogFacility			= LOG_LOCAL0;
+/** Defines the Syslog facility number used for activity messages.  Defaults to LOG_LOCAL1. */
 static int _osrfLogActFacility		= LOG_LOCAL1;
+/** Name of the log file. */
 static char* _osrfLogFile			= NULL;
+/** Application name.  This string will preface every log message. */
 static char* _osrfLogAppname		= NULL;
+/** Maximum message level.  Messages of higher levels will be suppressed.
+	Default: OSRF_LOG_INFO. */
 static int _osrfLogLevel			= OSRF_LOG_INFO;
+/** Boolean.  If true, activity message are enabled.  Default: true. */
 static int _osrfLogActivityEnabled	= 1;
+/** Boolean.  If true, the current process is a client; otherwise it's a server.  Clients and
+	servers have different options with regard to transaction ids.  See osrfLogSetXid(),
+	osrfLogForceXid(), and osrfLogMkXid().  Default: false. */
 static int _osrfLogIsClient         = 0;
 
+/** An id identifying the current transaction.  If defined, it is included into every
+	log message. */
 static char* _osrfLogXid            = NULL; /* current xid */
+/** A prefix used to generate transaction ids.  It incorporates a timestamp and a process id. */
 static char* _osrfLogXidPfx         = NULL; /* xid prefix string */
 
 static void osrfLogSetType( int logtype );
@@ -27,7 +45,7 @@
 static void _osrfLogSetXid( const char* xid );
 
 /**
-	@brief Reset certain static variables to their initial values.
+	@brief Reset certain local static variables to their initial values.
 
 	Of the various static variables, we here reset only three:
 	- application name (deleted)
@@ -62,10 +80,8 @@
 	The logging type may be set separately by calling osrfLogSetType().  See also
 	osrfLogToStderr() and osrfRestoreLogType().
 
-	The @a appname string prefaces every log message written to a log file or to standard
-	error.  It also identifies the application to the Syslog facility, if the application
-	uses Syslog.  The default application name, if not overridden by this function or by
-	osrfLogSetAppname(), is "osrf".
+	The @a appname string prefaces every log message.  The default application name, if
+	not overridden by this function or by osrfLogSetAppname(), is "osrf".
 
 	Here are the valid values for @a maxlevel, with the corresponding macros:
 
@@ -115,7 +131,7 @@
 }
 
 /**
-	@brief Store a transaction id, unconditionally, for future use.
+	@brief Store a transaction id for future use, whether running as a client or as a server.
 	@param xid Pointer to the new transaction id
 */
 void osrfLogForceXid(char* xid) {
@@ -202,6 +218,11 @@
 	}
 }
 
+/**
+	@brief Switch the logging output to standard error (but remember where it @em was going).
+
+	See also osrfRestoreLogType().
+*/
 void osrfLogToStderr( void )
 {
 	if( OSRF_NO_LOG_TYPE == _prevLogType ) {
@@ -210,6 +231,13 @@
 	}
 }
 
+/**
+	@brief Switch the logging output to wherever it was going before calling osrfLogtoStderr().
+
+	By using osrfRestoreLogType together with osrfRestoreLogType(), an application can
+	temporarily redirect log messages to standard error, either for an interactive
+	session or for debugging, and later revert to the original log output.
+*/
 void osrfRestoreLogType( void )
 {
 	if( _prevLogType != OSRF_NO_LOG_TYPE ) {
@@ -218,16 +246,36 @@
 	}
 }
 
+/**
+	@brief Store a file name for a log file.
+	@param logfile Pointer to the file name.
+
+	The new file name replaces whatever file name was previously in place, if any.
+
+	This function does not affect the logging type.  The choice of file name makes a
+	difference only when the logging type is OSRF_LOG_TYPE_FILE.
+*/
 void osrfLogSetFile( const char* logfile ) {
 	if(!logfile) return;
 	if(_osrfLogFile) free(_osrfLogFile);
 	_osrfLogFile = strdup(logfile);
 }
 
+/**
+	@brief Enable the issuance of activity log messages.
+
+	By default, activity messages are enabled.  See also osrfLogActivity().
+*/
 void osrfLogSetActivityEnabled( int enabled ) {
 	_osrfLogActivityEnabled = enabled;
 }
 
+/**
+	@brief Store an application name for future use.
+	@param appname Pointer to the application name to be stored.
+
+	The @a appname string prefaces every log message.  The default application name is "osrf".
+*/
 void osrfLogSetAppname( const char* appname ) {
 	if(!appname) return;
 	if(_osrfLogAppname) free(_osrfLogAppname);
@@ -240,24 +288,85 @@
 	}
 }
 
+/**
+	@brief Store a facility number for future use.
+	@param facility The facility number to be stored.
+
+	A facility is a small integer passed to the Syslog system to characterize the source
+	of a message.  The value of this integer is typically derived from a configuration file.
+	If not otherwise specified, it defaults to LOG_LOCAL0.
+*/
 void osrfLogSetSyslogFacility( int facility ) {
 	_osrfLogFacility = facility;
 }
+
+/**
+	@brief Store a facility number for future use for activity messages.
+	@param facility The facility number to be stored.
+
+	A facility is a small integer passed to the Syslog system to characterize the source
+	of a message.  The value of this integer is typically derived from a configuration file.
+
+	The facility used for activity messages is separate and distinct from that used for
+	other log messages, and defaults to LOG_LOCAL1.
+ */
 void osrfLogSetSyslogActFacility( int facility ) {
 	_osrfLogActFacility = facility;
 }
 
-/** Sets the global log level.  Any log statements with a higher level
- * than "level" will not be logged */
+/**
+	@brief Set the maximum level of messages to be issued.
+	@param loglevel The maximum message level.
+
+	A log message will be issued only if its level is less than or equal to this maximum.
+	For example, if @a loglevel is set to OSRF_LOG_INFO, then the logging routines will
+	issue information messages, warning messages, and error messages, but not debugging
+	messages or internal messages.
+
+	The default message level is OSRF_LOG_INFO.
+*/
 void osrfLogSetLevel( int loglevel ) {
 	_osrfLogLevel = loglevel;
 }
 
-/** Gets the current global log level. **/
+/**
+	@brief Get the current log message level.
+	@return The current log message level.
+
+	See also osrfLogSetLevel().
+ */
 int osrfLogGetLevel( void ) {
 	return _osrfLogLevel;
 }
 
+/**
+	@name Message Logging Functions
+	
+	These five functions are the most widely used of the logging routines.  They all work
+	the same way, differing only in the levels of the messages they log, and in the tags
+	they use within those messages to indicate the message level.
+
+	The first two parameters define the location in the source code where the function is
+	called: the name of the source file and the line number.  In practice these are normally
+	provided through use of the OSRF_LOG_MARK macro.
+
+	The third parameter is a printf-style format string, which will be expanded to form the
+	message text.  Subsequent parameters, if any, will be formatted and inserted into the
+	expanded message text.
+
+	Depending on the current maximum message level, the message may or may not actually be
+	issued.  See also osrfLogSetLevel().
+*/
+/*@{*/
+
+/**
+	@brief Log an error message.
+	@param file The file name of the source code calling the function.
+	@param line The line number of the source code calling the function.
+	@param msg A printf-style format string that will be expanded to form the message text,
+
+	Tag: "ERR".
+*/
 void osrfLogError( const char* file, int line, const char* msg, ... ) {
 	if( !msg ) return;
 	if( _osrfLogLevel < OSRF_LOG_ERROR ) return;
@@ -265,6 +374,14 @@
 	_osrfLogDetail( OSRF_LOG_ERROR, file, line, VA_BUF );
 }
 
+/**
+	@brief Log a warning message.
+	@param file The file name of the source code calling the function.
+	@param line The line number of the source code calling the function.
+	@param msg A printf-style format string that will be expanded to form the message text,
+
+	Tag: "WARN".
+ */
 void osrfLogWarning( const char* file, int line, const char* msg, ... ) {
 	if( !msg ) return;
 	if( _osrfLogLevel < OSRF_LOG_WARNING ) return;
@@ -272,6 +389,14 @@
 	_osrfLogDetail( OSRF_LOG_WARNING, file, line, VA_BUF );
 }
 
+/**
+	@brief Log an informational message.
+	@param file The file name of the source code calling the function.
+	@param line The line number of the source code calling the function.
+	@param msg A printf-style format string that will be expanded to form the message text,
+
+	Tag: "INFO".
+ */
 void osrfLogInfo( const char* file, int line, const char* msg, ... ) {
 	if( !msg ) return;
 	if( _osrfLogLevel < OSRF_LOG_INFO ) return;
@@ -279,6 +404,14 @@
 	_osrfLogDetail( OSRF_LOG_INFO, file, line, VA_BUF );
 }
 
+/**
+	@brief Log a debug message.
+	@param file The file name of the source code calling the function.
+	@param line The line number of the source code calling the function.
+	@param msg A printf-style format string that will be expanded to form the message text,
+ 
+	Tag: "DEBG".
+ */
 void osrfLogDebug( const char* file, int line, const char* msg, ... ) {
 	if( !msg ) return;
 	if( _osrfLogLevel < OSRF_LOG_DEBUG ) return;
@@ -286,6 +419,14 @@
 	_osrfLogDetail( OSRF_LOG_DEBUG, file, line, VA_BUF );
 }
 
+/**
+	@brief Log an internal message.
+	@param file The file name of the source code calling the function.
+	@param line The line number of the source code calling the function.
+	@param msg A printf-style format string that will be expanded to form the message text,
+
+	Tag: "INT ".
+ */
 void osrfLogInternal( const char* file, int line, const char* msg, ... ) {
 	if( !msg ) return;
 	if( _osrfLogLevel < OSRF_LOG_INTERNAL ) return;
@@ -293,6 +434,23 @@
 	_osrfLogDetail( OSRF_LOG_INTERNAL, file, line, VA_BUF );
 }
 
+/*@}*/
+
+/**
+	@brief Issue activity log message.
+	@param file The file name of the source code calling the function.
+	@param line The line number of the source code calling the function.
+	@param msg A printf-style format string that will be expanded to form the message text,
+
+	Tag: "ACT".
+
+	Activity messages behave like informational messages, with the following differences:
+	- They are tagged "ACT" instead of "INFO";
+	- Though enabled by default, they may be disabled by a previous call to
+		osrfLogSetActivityEnabled();
+	- When Syslog is in use, they are assigned a separate facility number, which defaults
+		to LOG_LOCAL1 instead of LOG_LOCAL0.  See also osrfLogSetSyslogActFacility().
+*/
 void osrfLogActivity( const char* file, int line, const char* msg, ... ) {
 	if( !msg ) return;
 	if( _osrfLogLevel >= OSRF_LOG_INFO
@@ -326,6 +484,9 @@
 
 	Here we format the message and route it to the appropriate output destination, depending
 	on the current setting of _osrfLogType: Syslog, a log file, or standard error.
+
+	If the logging type has been set to OSRF_LOG_TYPE_FILE, but no file name has been
+	defined for the log file, the message is written to standard error.
 */
 static void _osrfLogDetail( int level, const char* filename, int line, char* msg ) {
 
@@ -443,6 +604,21 @@
 
 }
 
+/**
+	@brief Translate a character string to a facility number for Syslog.
+	@param facility The string to be translated.
+	@return An integer in the range 0 through 7.
+
+	Take the sixth character (counting from 1).  If it's a digit in the range '0' through '7',
+	return the corresponding value: LOG_LOCAL0, LOG_LOCAL1, etc...  Otherwise -- or if the
+	string isn't long enough -- return LOG_LOCAL0 as a default.
+
+	Example: "LOCAL3" => LOG_LOCAL3.
+
+	(Syslog uses the LOG_LOCALx macros to designate different kinds of locally defined
+	facilities that may issue messages.  Depending on the configuration, Syslog mey handle
+	messages from different facilities differently.)
+*/
 int osrfLogFacilityToInt( const char* facility ) {
 	if(!facility) return LOG_LOCAL0;
 	if(strlen(facility) < 6) return LOG_LOCAL0;



More information about the opensrf-commits mailing list