|
NSPR Reference Previous Contents Next |
Chapter 26 Logging
printf() style strings
to the console or to a log file. NSPR uses this facility itself for its own development
debugging purposes.
You can select events to be logged by module or level. A module is a user-defined class of log events. A level is a numeric value that indicates the seriousness of the event to be logged. You can combine module and level criteria to get highly selective logging.
NSPR also provides "assert"-style macros and functions to aid in application debugging.
Conditional Compilation and Execution
Log Types and Variables
Logging Functions and Macros
Use Example
Conditional Compilation and Execution
NSPR's logging facility is conditionally compiled in and enabled for applications using it. These controls are platform dependent. Logging is not compiled in for the Win16 platform. Logging is compiled into the NSPR debug builds; logging is not compiled into the NSPR optimized builds. The compile time#define values DEBUG
or FORCE_PR_LOG enable NSPR logging for application programs.
To enable NSPR logging and/or the debugging aids in your application, compile using the NSPR debug build headers and runtime. Set one of the compile-time defines when you build your application.
Execution-time control of NSPR's logging uses two environment variables. These variables control which modules and levels are logged as well as the file name of the log file. By default, no logging is enabled at execution time.
Log Types and Variables
Two types supporting NSPR logging are exposed in the API:
PRLogModuleInfo
PRLogModuleLevel
Two environment variables control the behavior of logging at execution time:
NSPR_LOG_MODULES
NSPR_LOG_FILE
PRLogModuleInfo
ThePRLogModuleInfo structure controls logging from within your application. To
log your program's activity, create a PRLogModuleInfo structure using
PR_NewLogModule .
Syntax
#include <prlog.h>
typedef struct PRLogModuleInfo {
const char *name;
PRLogModuleLevel level;
struct PRLogModuleInfo *next;
} PRLogModuleInfo;
PRLogModuleLevel
The enumerated typePRLogModuleLevel defines levels of logging available to
application programs.
Syntax
#include <prlog.h>
typedef enum PRLogModuleLevel {
PR_LOG_NONE = 0,
PR_LOG_ALWAYS = 1,
PR_LOG_ERROR = 2,
PR_LOG_WARNING = 3,
PR_LOG_DEBUG = 4,
PR_LOG_NOTICE = PR_LOG_DEBUG,
PR_LOG_WARN = PR_LOG_WARNING,
PR_LOG_MIN = PR_LOG_DEBUG,
PR_LOG_MAX = PR_LOG_DEBUG
} PRLogModuleLevel;
NSPR_LOG_MODULES
This environment variable specifies which log modules have logging enabled.Syntax
moduleName:level[, moduleName:level]*
moduleName is the name specified in a PR_NewLogModule call.
level is a numeric value in the range PR_LOG_NONE to PR_LOG_MAX.
Description
Specify amoduleName that is associated with the name argument in a call to
PR_NewLogModule and a non-zero level value to enable logging for the named
moduleName.
Special log module names are provided for controlling NSPR's log service at
execution time. These controls should be set in the NSPR_LOG_MODULES
environment variable at execution time to affect NSPR's log service for your
application.
-
The name
all enables all log modules. To enable all log module calls to
PR_LOG, set the variable as follows:
set NSPR_LOG_MODULES=all:5
The name sync enables unbuffered logging.
The name bufsize:size sets the log buffer to size.
NSPR_LOG_FILE
This environment variable specifies the file to which log messages are directed.Syntax
filespec
filespec is a filename. The exact syntax is platform specific.
Description
Use this environment variable to specify a log file other than the default. IfNSPR_LOG_FILE is not in the environment, then log output is written to stdout or
stderr, depending on the platform. Set NSPR_LOG_FILE to the name of the log file
you want to use. NSPR logging, when enabled, writes to the file named in this
environment variable.
For MS Windows systems, you can set NSPR_LOG_FILE to the special
(case-sensitive) value WinDebug. This value causes logging output to be written
using the Windows function OutputDebugString(), which writes to the debugger
window.
Logging Functions and Macros
The functions and macros for logging are:
PR_NewLogModule
PR_SetLogFile
PR_SetLogBuffering
PR_LogPrint
PR_LogFlush
PR_LOG_TEST
PR_LOG
PR_Assert
PR_ASSERT
PR_NOT_REACHED
PR_NewLogModule
Creates a new log module.Syntax
#include <prlog.h>
PRLogModuleInfo* PR_NewLogModule(const char *name);
Parameters
The function has this parameter:
|
name
|
The name to be assigned to the PRLogModuleInfo structure.
|
Returns
A pointer to aPRLogModuleInfo structure.
Description
This function allocates and initializes a newPRLogModuleInfo structure with the
specified name. If the environment variable NSPR_LOG_MODULES contains the
specified name, then the associated level value from the variable is associated with
the new PRLogModuleInfo structure.
PR_SetLogFile
Sets the name of the log file.Syntax
#include <prlog.h>
PRBool PR_SetLogFile(const char *name);
Parameter
The function has this parameter:
name
|
The name of the log file.
|
Returns
PR_TRUE when successful. Otherwise, PR_FALSE.
Description
Creates a log file with the specified file name. Subsequent log messages are written to this file.Ordinarily, a user application need not use this function, as NSPR initializes logging at NSPR startup. The application can use the model provided in Use Example to effect application logging.
PR_SetLogBuffering
Sets the level of buffering for the log file.Syntax
#include <prlog.h>
void PR_SetLogBuffering(PRIntn buffer_size);
Parameters
The function has this parameter:
buffer_size
|
The size of the buffer to be used for logging.
|
Returns
Nothing.Description
This function sets the size of the buffer used in NSPR logging.Ordinarily, a user application need not use this function, as NSPR initializes logging at NSPR startup. The application can use the model provided in Use Example to effect application logging.
PR_LogPrint
Writes an entry to the log.Syntax
#include <prlog.h>
void PR_LogPrint(const char *fmt, ...);
Parameters
The function has this parameter:
fmt
|
The string that is used as the formatting specification.
|
Returns
Nothing.Description
This function unconditionally writes a message to the log using the specified format string. For a description of formatting and format strings, see Chapter 20 "Formatted Printing."PR_LogFlush
Flushes the log buffer to external media.Syntax
#include <prlog.h>
void PR_LogFlush(void);
Parameter
The function has no parameters.Returns
Nothing.Description
This function flushes the log buffer to external media.PR_LOG_TEST
Determines if logging is enabled for a module and level.Syntax
#include <prlog.h>
PRBool PR_LOG_TEST (
PRLogModuleInfo *_module,
PRLogModuleLevel _level);
Parameters
The macro has these parameters:
Returns
PR_TRUE when logging is enabled for the given module and level, otherwise
PR_FALSE.
Description
This macro tests whether logging is enabled for the specified module and level. Use it as an expression in a conditional execution statement to control logging. See alsoPR_LOG.
PR_LOG
Conditionally writes an entry to the log.Syntax
#include <prlog.h>
void PR_LOG (
PRLogModuleInfo *_module,
PRLogModuleLevel _level
... _args);
Parameters
The macro has these parameters:
Returns
Nothing.Description
This macro formats the specified arguments and writes the output to the log file, if logging is enabled for the specified module and level. For a description of formatting and format strings, see Chapter 20 "Formatted Printing"For an example of using conditional logging, see Use Example .
This macro compiles to nothing if compile-time options are not specified to enable logging.
PR_Assert
Writes arguments to the log and terminates execution.Syntax
#include <prlog.h>
void PR_Assert (
const char *s,
const char *file,
PRIntn ln);
Parameters
The function has these parameters:
s
|
A string to be displayed in the log
|
file
|
The file name of the compilation unit containing this function call.
|
ln
|
The line number within the specified file of this function call.
|
Returns
Nothing.Description
This function displays data in the log.
Normally an application would not call this function directly; use PR_ASSERT
instead.
PR_ASSERT
Terminates execution when a given expression isFALSE.
Syntax
#include <prlog.h>
void PR_ASSERT ( expression );
Parameters
The macro has this parameter:
expression
|
Any valid C language expression that evaluates to TRUE or FALSE.
|
Returns
NothingDescription
This macro evaluates the specified expression. When the result is zero (FALSE) the
application terminates; otherwise the application continues. The macro converts
the expression to a string and passes it to PR_Assert, using file and ln
parameters from the compile-time environment.
This macro compiles to nothing if compile-time options are not specified to enable logging.
PR_NOT_REACHED
Terminates the calling application with a message to the log.Syntax
#include <prlog.h>
void PR_NOT_REACHED(const char *_reasonStr);
Parameters
The macro has this parameter:
reasonStr
|
A string that describes why you should not have reached this
statement.
|
Returns
Nothing.Description
This macro writes the specified reason string to the log and terminates the application.This macro compiles to nothing if compile-time options are not specified to enable logging.
Use Example
The following sample code fragment demonstrates use of the logging and debugging aids.
-
Compile the program with
DEBUG defined.
Before running the compiled program, set the environment variable
NSPR_LOG_MODULES to userStuff:5
static void UserLogStuff( void )
{
PRLogModuleInfo *myLM;
PRIntn i;
myLM = PR_NewLogModule( "userStuff" );
PR_ASSERT( myLM );
PR_LOG( myLM, PR_LOG_NOTICE, ("Log a Notice %d\n", 999 ));
for (i = 0; i < 10 ; i++ )
{
PR_LOG( myLM, PR_LOG_DEBUG, ("Log Debug number: %d\n", i));
PR_Sleep( 500 );
}
PR_LOG( myLM, PR_LOG_NOTICE, ("That's all folks\n");
} /* end UserLogStuff() */
Last Updated May 18, 2001