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