nsprpub/pr/include/prlog.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef prlog_h___
   7 #define prlog_h___
   8
   9 #include "prtypes.h"
  10
  11 PR_BEGIN_EXTERN_C
  12
  13 /*
  14 ** prlog.h -- Declare interfaces to NSPR's Logging service
  15 **
  16 ** NSPR provides a logging service that is used by NSPR itself and is
  17 ** available to client programs.
  18 **
  19 ** To use the service from a client program, you should create a
  20 ** PRLogModuleInfo structure by calling PR_NewLogModule(). After
  21 ** creating the LogModule, you can write to the log using the PR_LOG()
  22 ** macro.
  23 **
  24 ** Initialization of the log service is handled by NSPR initialization.
  25 **
  26 ** At execution time, you must enable the log service. To enable the
  27 ** log service, set the environment variable: NSPR_LOG_MODULES
  28 ** variable.
  29 **
  30 ** NSPR_LOG_MODULES variable has the form:
  31 **
  32 **     <moduleName>:<value>[, <moduleName>:<value>]*
  33 **
  34 ** Where:
  35 **  <moduleName> is the name passed to PR_NewLogModule().
  36 **  <value> is a numeric constant, e.g. 5. This value is the maximum
  37 ** value of a log event, enumerated by PRLogModuleLevel, that you want
  38 ** written to the log.
  39 **
  40 ** For example: to record all events of greater value than or equal to
  41 ** PR_LOG_ERROR for a LogModule names "gizmo", say:
  42 **
  43 ** set NSPR_LOG_MODULES=gizmo:2
  44 **
  45 ** Note that you must specify the numeric value of PR_LOG_ERROR.
  46 **
  47 ** Special LogModule names are provided for controlling NSPR's log
  48 ** service at execution time. These controls should be set in the
  49 ** NSPR_LOG_MODULES environment variable at execution time to affect
  50 ** NSPR's log service for your application.
  51 **
  52 ** The special LogModule "all" enables all LogModules. To enable all
  53 ** LogModule calls to PR_LOG(), say:
  54 **
  55 ** set NSPR_LOG_MODULES=all:5
  56 **
  57 ** The special LogModule name "sync" tells the NSPR log service to do
  58 ** unbuffered logging.
  59 **
  60 ** The special LogModule name "bufsize:<size>" tells NSPR to set the
  61 ** log buffer to <size>.
  62 **
  63 ** The environment variable NSPR_LOG_FILE specifies the log file to use
  64 ** unless the default of "stderr" is acceptable. For MS Windows
  65 ** systems, NSPR_LOG_FILE can be set to a special value: "WinDebug"
  66 ** (case sensitive). This value causes PR_LOG() output to be written
  67 ** using the Windows API OutputDebugString(). OutputDebugString()
  68 ** writes to the debugger window; some people find this helpful.
  69 **
  70 **
  71 ** To put log messages in your programs, use the PR_LOG macro:
  72 **
  73 **     PR_LOG(<module>, <level>, (<printfString>, <args>*));
  74 **
  75 ** Where <module> is the address of a PRLogModuleInfo structure, and
  76 ** <level> is one of the levels defined by the enumeration:
  77 ** PRLogModuleLevel. <args> is a printf() style of argument list. That
  78 ** is: (fmtstring, ...).
  79 **
  80 ** Example:
  81 **
  82 ** main() {
  83 **    PRIntn one = 1;
  84 **    PRLogModuleInfo * myLm = PR_NewLogModule("gizmo");
  85 **    PR_LOG( myLm, PR_LOG_ALWAYS, ("Log this! %d\n", one));
  86 **    return;
  87 ** }
  88 **
  89 ** Note the use of printf() style arguments as the third agrument(s) to
  90 ** PR_LOG().
  91 **
  92 ** After compiling and linking you application, set the environment:
  93 **
  94 ** set NSPR_LOG_MODULES=gizmo:5
  95 ** set NSPR_LOG_FILE=logfile.txt
  96 **
  97 ** When you execute your application, the string "Log this! 1" will be
  98 ** written to the file "logfile.txt".
  99 **
 100 ** Note to NSPR engineers: a number of PRLogModuleInfo structures are
 101 ** defined and initialized in prinit.c. See this module for ideas on
 102 ** what to log where.
 103 **
 104 */
 105
 106 typedef enum PRLogModuleLevel {
 107     PR_LOG_NONE = 0,                /* nothing */
 108     PR_LOG_ALWAYS = 1,              /* always printed */
 109     PR_LOG_ERROR = 2,               /* error messages */
 110     PR_LOG_WARNING = 3,             /* warning messages */
 111     PR_LOG_DEBUG = 4,               /* debug messages */
 112
 113     PR_LOG_NOTICE = PR_LOG_DEBUG,   /* notice messages */
 114     PR_LOG_WARN = PR_LOG_WARNING,   /* warning messages */
 115     PR_LOG_MIN = PR_LOG_DEBUG,      /* minimal debugging messages */
 116     PR_LOG_MAX = PR_LOG_DEBUG       /* maximal debugging messages */
 117 } PRLogModuleLevel;
 118
 119 /*
 120 ** One of these structures is created for each module that uses logging.
 121 **    "name" is the name of the module
 122 **    "level" is the debugging level selected for that module
 123 */
 124 typedef struct PRLogModuleInfo {
 125     const char *name;
 126     PRLogModuleLevel level;
 127     struct PRLogModuleInfo *next;
 128 } PRLogModuleInfo;
 129
 130 /*
 131 ** Create a new log module.
 132 */
 133 NSPR_API(PRLogModuleInfo*) PR_NewLogModule(const char *name);
 134
 135 /*
 136 ** Set the file to use for logging. Returns PR_FALSE if the file cannot
 137 ** be created
 138 */
 139 NSPR_API(PRBool) PR_SetLogFile(const char *name);
 140
 141 /*
 142 ** Set the size of the logging buffer. If "buffer_size" is zero then the
 143 ** logging becomes "synchronous" (or unbuffered).
 144 */
 145 NSPR_API(void) PR_SetLogBuffering(PRIntn buffer_size);
 146
 147 /*
 148 ** Print a string to the log. "fmt" is a PR_snprintf format type. All
 149 ** messages printed to the log are preceeded by the name of the thread
 150 ** and a time stamp. Also, the routine provides a missing newline if one
 151 ** is not provided.
 152 */
 153 NSPR_API(void) PR_LogPrint(const char *fmt, ...);
 154
 155 /*
 156 ** Flush the log to its file.
 157 */
 158 NSPR_API(void) PR_LogFlush(void);
 159
 160 NSPR_API(void) PR_Assert(const char *s, const char *file, PRIntn ln)
 161 PR_PRETEND_NORETURN;
 162
 163 #if defined(DEBUG) || defined(FORCE_PR_LOG)
 164 #define PR_LOGGING 1
 165
 166 #define PR_LOG_TEST(_module,_level) \
 167     ((_module)->level >= (_level))
 168
 169 /*
 170 ** Log something.
 171 **    "module" is the address of a PRLogModuleInfo structure
 172 **    "level" is the desired logging level
 173 **    "args" is a variable length list of arguments to print, in the following
 174 **       format:  ("printf style format string", ...)
 175 */
 176 #define PR_LOG(_module,_level,_args)     \
 177     PR_BEGIN_MACRO             \
 178       if (PR_LOG_TEST(_module,_level)) { \
 179       PR_LogPrint _args;         \
 180       }                     \
 181     PR_END_MACRO
 182
 183 #else /* defined(DEBUG) || defined(FORCE_PR_LOG) */
 184
 185 #undef PR_LOGGING
 186 #define PR_LOG_TEST(module,level) 0
 187 #define PR_LOG(module,level,args)
 188
 189 #endif /* defined(DEBUG) || defined(FORCE_PR_LOG) */
 190
 191 #ifndef NO_NSPR_10_SUPPORT
 192
 193 #ifdef PR_LOGGING
 194 #define PR_LOG_BEGIN    PR_LOG
 195 #define PR_LOG_END      PR_LOG
 196 #define PR_LOG_DEFINE   PR_NewLogModule
 197 #else
 198 #define PR_LOG_BEGIN(module,level,args)
 199 #define PR_LOG_END(module,level,args)
 200 #define PR_LOG_DEFINE(_name)    NULL
 201 #endif /* PR_LOGGING */
 202
 203 #endif /* NO_NSPR_10_SUPPORT */
 204
 205 #if defined(DEBUG) || defined(FORCE_PR_ASSERT)
 206
 207 #define PR_ASSERT(_expr) \
 208     ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
 209
 210 #define PR_ASSERT_ARG(_expr) PR_ASSERT(_expr)
 211
 212 #define PR_NOT_REACHED(_reasonStr) \
 213     PR_Assert(_reasonStr,__FILE__,__LINE__)
 214
 215 #else
 216
 217 #define PR_ASSERT(expr) ((void) 0)
 218 /* PR_ASSERT_ARG avoids compiler warning: unused variable */
 219 #define PR_ASSERT_ARG(expr) ((void)(0 && (expr)))
 220 #define PR_NOT_REACHED(reasonStr)
 221
 222 #endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
 223
 224 PR_END_EXTERN_C
 225
 226 #endif /* prlog_h___ */