The Tor Browser / file comparison

comparison: nsprpub/pr/include/prlog.h

nsprpub/pr/include/prlog.h

changeset 2
7e26c7da4463
equal deleted inserted replaced
-1:000000000000 0:45aa44dc22ed
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
162 #if defined(DEBUG) || defined(FORCE_PR_LOG)
163 #define PR_LOGGING 1
164
165 #define PR_LOG_TEST(_module,_level) \
166 ((_module)->level >= (_level))
167
168 /*
169 ** Log something.
170 ** "module" is the address of a PRLogModuleInfo structure
171 ** "level" is the desired logging level
172 ** "args" is a variable length list of arguments to print, in the following
173 ** format: ("printf style format string", ...)
174 */
175 #define PR_LOG(_module,_level,_args) \
176 PR_BEGIN_MACRO \
177 if (PR_LOG_TEST(_module,_level)) { \
178 PR_LogPrint _args; \
179 } \
180 PR_END_MACRO
181
182 #else /* defined(DEBUG) || defined(FORCE_PR_LOG) */
183
184 #undef PR_LOGGING
185 #define PR_LOG_TEST(module,level) 0
186 #define PR_LOG(module,level,args)
187
188 #endif /* defined(DEBUG) || defined(FORCE_PR_LOG) */
189
190 #ifndef NO_NSPR_10_SUPPORT
191
192 #ifdef PR_LOGGING
193 #define PR_LOG_BEGIN PR_LOG
194 #define PR_LOG_END PR_LOG
195 #define PR_LOG_DEFINE PR_NewLogModule
196 #else
197 #define PR_LOG_BEGIN(module,level,args)
198 #define PR_LOG_END(module,level,args)
199 #define PR_LOG_DEFINE(_name) NULL
200 #endif /* PR_LOGGING */
201
202 #endif /* NO_NSPR_10_SUPPORT */
203
204 #if defined(DEBUG) || defined(FORCE_PR_ASSERT)
205
206 #define PR_ASSERT(_expr) \
207 ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
208
209 #define PR_NOT_REACHED(_reasonStr) \
210 PR_Assert(_reasonStr,__FILE__,__LINE__)
211
212 #else
213
214 #define PR_ASSERT(expr) ((void) 0)
215 #define PR_NOT_REACHED(reasonStr)
216
217 #endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
218
219 PR_END_EXTERN_C
220
221 #endif /* prlog_h___ */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial