prlog.h (7050B)
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___ */