andre@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
andre@0: /* This Source Code Form is subject to the terms of the Mozilla Public
andre@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
andre@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
andre@0: 
andre@0: #ifndef prlog_h___
andre@0: #define prlog_h___
andre@0: 
andre@0: #include "prtypes.h"
andre@0: 
andre@0: PR_BEGIN_EXTERN_C
andre@0: 
andre@0: /*
andre@0: ** prlog.h -- Declare interfaces to NSPR's Logging service
andre@0: **
andre@0: ** NSPR provides a logging service that is used by NSPR itself and is
andre@0: ** available to client programs.
andre@0: **
andre@0: ** To use the service from a client program, you should create a
andre@0: ** PRLogModuleInfo structure by calling PR_NewLogModule(). After
andre@0: ** creating the LogModule, you can write to the log using the PR_LOG()
andre@0: ** macro.
andre@0: **
andre@0: ** Initialization of the log service is handled by NSPR initialization.
andre@0: **
andre@0: ** At execution time, you must enable the log service. To enable the
andre@0: ** log service, set the environment variable: NSPR_LOG_MODULES
andre@0: ** variable.
andre@0: **
andre@0: ** NSPR_LOG_MODULES variable has the form:
andre@0: **
andre@0: **     <moduleName>:<value>[, <moduleName>:<value>]*
andre@0: **
andre@0: ** Where:
andre@0: **  <moduleName> is the name passed to PR_NewLogModule().
andre@0: **  <value> is a numeric constant, e.g. 5. This value is the maximum
andre@0: ** value of a log event, enumerated by PRLogModuleLevel, that you want
andre@0: ** written to the log.
andre@0: ** 
andre@0: ** For example: to record all events of greater value than or equal to
andre@0: ** PR_LOG_ERROR for a LogModule names "gizmo", say:
andre@0: ** 
andre@0: ** set NSPR_LOG_MODULES=gizmo:2
andre@0: ** 
andre@0: ** Note that you must specify the numeric value of PR_LOG_ERROR.
andre@0: ** 
andre@0: ** Special LogModule names are provided for controlling NSPR's log
andre@0: ** service at execution time. These controls should be set in the
andre@0: ** NSPR_LOG_MODULES environment variable at execution time to affect
andre@0: ** NSPR's log service for your application.
andre@0: ** 
andre@0: ** The special LogModule "all" enables all LogModules. To enable all
andre@0: ** LogModule calls to PR_LOG(), say:
andre@0: ** 
andre@0: ** set NSPR_LOG_MODULES=all:5
andre@0: ** 
andre@0: ** The special LogModule name "sync" tells the NSPR log service to do
andre@0: ** unbuffered logging.
andre@0: ** 
andre@0: ** The special LogModule name "bufsize:<size>" tells NSPR to set the
andre@0: ** log buffer to <size>.
andre@0: **
andre@0: ** The environment variable NSPR_LOG_FILE specifies the log file to use
andre@0: ** unless the default of "stderr" is acceptable. For MS Windows
andre@0: ** systems, NSPR_LOG_FILE can be set to a special value: "WinDebug"
andre@0: ** (case sensitive). This value causes PR_LOG() output to be written
andre@0: ** using the Windows API OutputDebugString(). OutputDebugString()
andre@0: ** writes to the debugger window; some people find this helpful.
andre@0: ** 
andre@0: **
andre@0: ** To put log messages in your programs, use the PR_LOG macro:
andre@0: **
andre@0: **     PR_LOG(<module>, <level>, (<printfString>, <args>*));
andre@0: **
andre@0: ** Where <module> is the address of a PRLogModuleInfo structure, and
andre@0: ** <level> is one of the levels defined by the enumeration:
andre@0: ** PRLogModuleLevel. <args> is a printf() style of argument list. That
andre@0: ** is: (fmtstring, ...).
andre@0: **
andre@0: ** Example:
andre@0: ** 
andre@0: ** main() {
andre@0: **    PRIntn one = 1;
andre@0: **    PRLogModuleInfo * myLm = PR_NewLogModule("gizmo");
andre@0: **    PR_LOG( myLm, PR_LOG_ALWAYS, ("Log this! %d\n", one)); 
andre@0: **    return; 
andre@0: ** }
andre@0: ** 
andre@0: ** Note the use of printf() style arguments as the third agrument(s) to
andre@0: ** PR_LOG().
andre@0: ** 
andre@0: ** After compiling and linking you application, set the environment:
andre@0: ** 
andre@0: ** set NSPR_LOG_MODULES=gizmo:5
andre@0: ** set NSPR_LOG_FILE=logfile.txt
andre@0: ** 
andre@0: ** When you execute your application, the string "Log this! 1" will be
andre@0: ** written to the file "logfile.txt".
andre@0: ** 
andre@0: ** Note to NSPR engineers: a number of PRLogModuleInfo structures are
andre@0: ** defined and initialized in prinit.c. See this module for ideas on
andre@0: ** what to log where.
andre@0: ** 
andre@0: */
andre@0: 
andre@0: typedef enum PRLogModuleLevel {
andre@0:     PR_LOG_NONE = 0,                /* nothing */
andre@0:     PR_LOG_ALWAYS = 1,              /* always printed */
andre@0:     PR_LOG_ERROR = 2,               /* error messages */
andre@0:     PR_LOG_WARNING = 3,             /* warning messages */
andre@0:     PR_LOG_DEBUG = 4,               /* debug messages */
andre@0: 
andre@0:     PR_LOG_NOTICE = PR_LOG_DEBUG,   /* notice messages */
andre@0:     PR_LOG_WARN = PR_LOG_WARNING,   /* warning messages */
andre@0:     PR_LOG_MIN = PR_LOG_DEBUG,      /* minimal debugging messages */
andre@0:     PR_LOG_MAX = PR_LOG_DEBUG       /* maximal debugging messages */
andre@0: } PRLogModuleLevel;
andre@0: 
andre@0: /*
andre@0: ** One of these structures is created for each module that uses logging.
andre@0: **    "name" is the name of the module
andre@0: **    "level" is the debugging level selected for that module
andre@0: */
andre@0: typedef struct PRLogModuleInfo {
andre@0:     const char *name;
andre@0:     PRLogModuleLevel level;
andre@0:     struct PRLogModuleInfo *next;
andre@0: } PRLogModuleInfo;
andre@0: 
andre@0: /*
andre@0: ** Create a new log module.
andre@0: */
andre@0: NSPR_API(PRLogModuleInfo*) PR_NewLogModule(const char *name);
andre@0: 
andre@0: /*
andre@0: ** Set the file to use for logging. Returns PR_FALSE if the file cannot
andre@0: ** be created
andre@0: */
andre@0: NSPR_API(PRBool) PR_SetLogFile(const char *name);
andre@0: 
andre@0: /*
andre@0: ** Set the size of the logging buffer. If "buffer_size" is zero then the
andre@0: ** logging becomes "synchronous" (or unbuffered).
andre@0: */
andre@0: NSPR_API(void) PR_SetLogBuffering(PRIntn buffer_size);
andre@0: 
andre@0: /*
andre@0: ** Print a string to the log. "fmt" is a PR_snprintf format type. All
andre@0: ** messages printed to the log are preceeded by the name of the thread
andre@0: ** and a time stamp. Also, the routine provides a missing newline if one
andre@0: ** is not provided.
andre@0: */
andre@0: NSPR_API(void) PR_LogPrint(const char *fmt, ...);
andre@0: 
andre@0: /*
andre@0: ** Flush the log to its file.
andre@0: */
andre@0: NSPR_API(void) PR_LogFlush(void);
andre@0: 
andre@0: NSPR_API(void) PR_Assert(const char *s, const char *file, PRIntn ln);
andre@0: 
andre@0: #if defined(DEBUG) || defined(FORCE_PR_LOG)
andre@0: #define PR_LOGGING 1
andre@0: 
andre@0: #define PR_LOG_TEST(_module,_level) \
andre@0:     ((_module)->level >= (_level))
andre@0: 
andre@0: /*
andre@0: ** Log something.
andre@0: **    "module" is the address of a PRLogModuleInfo structure
andre@0: **    "level" is the desired logging level
andre@0: **    "args" is a variable length list of arguments to print, in the following
andre@0: **       format:  ("printf style format string", ...)
andre@0: */
andre@0: #define PR_LOG(_module,_level,_args)     \
andre@0:     PR_BEGIN_MACRO             \
andre@0:       if (PR_LOG_TEST(_module,_level)) { \
andre@0:       PR_LogPrint _args;         \
andre@0:       }                     \
andre@0:     PR_END_MACRO
andre@0: 
andre@0: #else /* defined(DEBUG) || defined(FORCE_PR_LOG) */
andre@0: 
andre@0: #undef PR_LOGGING
andre@0: #define PR_LOG_TEST(module,level) 0
andre@0: #define PR_LOG(module,level,args)
andre@0: 
andre@0: #endif /* defined(DEBUG) || defined(FORCE_PR_LOG) */
andre@0: 
andre@0: #ifndef NO_NSPR_10_SUPPORT
andre@0: 
andre@0: #ifdef PR_LOGGING
andre@0: #define PR_LOG_BEGIN    PR_LOG
andre@0: #define PR_LOG_END      PR_LOG
andre@0: #define PR_LOG_DEFINE   PR_NewLogModule
andre@0: #else
andre@0: #define PR_LOG_BEGIN(module,level,args)
andre@0: #define PR_LOG_END(module,level,args)
andre@0: #define PR_LOG_DEFINE(_name)    NULL
andre@0: #endif /* PR_LOGGING */
andre@0: 
andre@0: #endif /* NO_NSPR_10_SUPPORT */
andre@0: 
andre@0: #if defined(DEBUG) || defined(FORCE_PR_ASSERT)
andre@0: 
andre@0: #define PR_ASSERT(_expr) \
andre@0:     ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
andre@0: 
andre@0: #define PR_NOT_REACHED(_reasonStr) \
andre@0:     PR_Assert(_reasonStr,__FILE__,__LINE__)
andre@0: 
andre@0: #else
andre@0: 
andre@0: #define PR_ASSERT(expr) ((void) 0)
andre@0: #define PR_NOT_REACHED(reasonStr)
andre@0: 
andre@0: #endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
andre@0: 
andre@0: PR_END_EXTERN_C
andre@0: 
andre@0: #endif /* prlog_h___ */