NSPR Reference: Chapter 26 Logging
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 26 Logging

This chapter describes the global functions you use to perform logging. NSPR provides a set of logging functions that conditionally write `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

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;

#### 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 a `moduleName` 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. If `NSPR_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 a `PRLogModuleInfo` structure.

##### Description

This function allocates and initializes a new `PRLogModuleInfo` 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:

`_module` | A pointer to a log module structure.
`_level` | A level value. Possible values are: `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`

##### 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 also `PR_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:

`_module` | A pointer to a log module structure.
`_level` | A level value. Possible values are: `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`
`_args` | A variable length argument list, as if to `printf`.

##### 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 is `FALSE`.

##### 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

Nothing

##### Description

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

Previous Contents Next

Last Updated May 18, 2001