The Mozilla
Organization
Our Mission
Who We Are
Getting Involved
Community
Editorials
What's New
Development
Roadmap
Module Owners
Blue Sky
Projects
Status
Tools
Products
Source Code
Binaries
Documentation
License Terms
Bug Reports
Search
Feedback


[Contents] [Previous] [Next][Last]

Chapter 18
Logging

This chapter describes the global functions you use to perform Logging. NSPR provides a set of Logging functions that will conditionally write printf() style strings to the console or to a log file. NSPR uses this facility itself for its own development debugging purposes. Logging, when enabled, can be selective. Selection is available on a "module" and "level" basis Where module is a user defined class of log events. Where level is a numeric value corresponding to a "seriousness" of the event to be logged. Combinations of module and level can be used to get highly selective logging.

NSPR also provides "assert" style of macros and functions to aid in application debugging.

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's enable NSPR logging for application programs: DEBUG or FORCE_PR_LOG.

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 filename of the logfile. By default, no logging is enabled at execution time.

Log Types

Two types supporting NSPR logging are exposed in the API:
PRLogModuleInfo
PRLogModuleLevel

PRLogModuleInfo

The PRLogModuleInfo 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 type PRLogModuleLevel 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;


Environment Variables

Two environment variables control the behavior of logging at execution time.
NSPR_LOG_MODULES
Syntax
<moduleName>:<level>[, <moduleName>:<level>]*
Where: <moduleName> is the name specificized in a PR_NewLogModuleInfo() call.
Where: <level> is a numeric value in the range PR_LOG_NONE to PR_LOG_MAX.
Description
Specifying a moduleName that is associated with the name argument in a call to PR_NewLogModule() with a non-zero <value> causes logging to be enabled for the named moduleName.

Special LogModule 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 special LogModule "all" enables all LogModules. To enable all LogModule calls to PR_LOG(), say: 

set NSPR_LOG_MODULES=all:5

The special LogModule name "sync" tells the NSPR log service to do unbuffered logging.

The special LogModule name "buffsize:<size>" tells NSPR to set the log buffer to <size>.

NSPR_LOG_FILE
Syntax
<filespec>
Where <filespec> is a filename. Note that the exact syntax of this is platform specific.
Description
NSPR_LOG_FILE is the name of the log file you want to use. NSPR logging, when enabled, will write to the file named in this environment variable. If NSPR_LOG_FILE is not in the environment, then log output will be written to stdout or stderr, depending on platform.

Functions and Macros

PR_NewLogModule

Syntax
#include <prlog.h>

PRLogModuleInfo* PR_NewLogModule(const char *name);

Parameter
name The name to be assigned to the PRLogModuleInfo structure.
Returns
A pointer to a PRLogModuleInfo structure.
Description
PR_NewLogModule() allocates and initializes a new PRLogModuleInfo structure. If the environment variable NSPR_LOG_MODULES contains name, then the value of level from the environment is associated with the new PRLogModuleInfo structure.


PR_SetLogFile

Set the name of the logfile
Syntax
#include <prlog.h>

PRBool PR_SetLogFile(const char *name);

Parameter
name The name of the logfile.
Returns
PR_TRUE when successful.
Description
Creates the named logfile. Subsequent requests to log will be written to this file.

Ordinarily, a user application need not use this API. NSPR initializes logging at NSPR startup. The application may use the model provided in Use Example to effect application logging.

PR_SetLogBuffering

Set the level of buffering for the logfile.
Syntax
#include <prlog.h>
void PR_SetLogBuffering(PRIntn buffer_size);

Parameter
buffer_size The size of the buffer used in logging.
Returns
void
Description
Set the size of the buffer used in NSPR logging.

Ordinarily, a user application need not use this API. NSPR initializes logging at NSPR startup. The application may use the model provided in Use Example to effect application logging.

PR_LogPrint

Unconditionally write an entry to the log.
Syntax
#include <prlog.h>
void PR_LogPrint(const char *fmt, ...);

Parameter
fmt an NSPR printf() style format string.
Returns
void
Description
Unconditionally writes to the log.

PR_LogFlush

Flush the log buffer to external media.
Syntax
#include <prlog.h>
void PR_LogFlush(void);

Parameter
none
Returns
void
Description
Flush the log buffer to external media.

PR_LOG_TEST

Test to determine if logging is enabled for _module at _level
Syntax
#include <prlog.h>
PRBool PR_LOG_TEST( PRLogModuleInfo *_module, PRLogModuleLevel _level);

Parameter
_module Pointer to a PRLogModuleInfo structure. 
_level
 A value defined in PRLogModuleLevel
Returns
PR_TRUE when logging is enabled for the referenced PRLogModuleInfo structure at _level, otherwise returns false.
Description
Use PR_LOG_TEST as an expression an a conditional execution statement to control logging. See also: PR_LOG

PR_LOG

Conditionally write to the log.
Syntax
#include <prlog.h>
void PR_LOG(_module,_level,_args);

Parameter
_module Pointer to a PRLogModuleInfo structure. 
_level
 A value defined in PRLogModuleLevel
_args A variable length argument list, as if to printf().
Returns
void
Description
If logging is enabled for _module at _level, then _args is formatted and written to the log. See Use Example .

PR_LOG() compiles to nothing if compile time options are not specified to enable logging.

PR_Assert

Write arguments to the log and terminate execution.
Syntax
#include <prlog.h>
void PR_Assert(const char *s, const char *file, PRIntn ln);

Parameter
s A string to be displayed in the log 
file
 A string. Normally the filename of the compilation unit containing the call to PR_Assert().
ln An integer. Normally the line number within file of the call to PR_Assert().
Returns
void
Description
Display data in the log.

Normally an application would not call PR_Assert() directly. Use PR_ASSERT() instead.

PR_ASSERT

Evaluate an expression. Terminate execution when ;alsdkfj
Syntax
#include <prlog.h>
void PR_ASSERT( expression );
Parameter
expression Any valid C language expression that evaluates to true or false.
Returns
void
Description
PR_ASSERT() evaluates expression. When expression evaluates to zero the application terminates, otherwise the application continues. PR_ASSERT() calls PR_Assert() with expression converted to a string, passed as argument s. The file and ln are provided from the compile time environment.

PR_ASSERT() compiles to nothing if compile time options are not specified to enable logging.

PR_NOT_REACHED

Terminate when reaching this statement.
Syntax
#include <prlog.h>
void PR_NOT_REACHED( char *_reasonStr)
Parameter
reasonStr A string. Why do you not think you should be here?.
Returns
void
Description
Write reasonStr to the log and terminate the application.

PR_NOT_REACHED() 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 debug aids.

Remember to 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() */

[Contents] [Previous] [Next][Last]
Last Updated: Tue Jul 14 16:19:14 PDT 1998
Copyright © 1998 Netscape Communications Corporation

Copyright © 1998 The Mozilla Organization.