Line data Source code
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 33 : 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 0 : 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 0 : 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 0 : NSPR_API(void) PR_LogPrint(const char *fmt, ...);
154 :
155 : /*
156 : ** Flush the log to its file.
157 : */
158 0 : NSPR_API(void) PR_LogFlush(void);
159 :
160 0 : 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_NOT_REACHED(_reasonStr) \
211 : PR_Assert(_reasonStr,__FILE__,__LINE__)
212 :
213 : #else
214 :
215 : #define PR_ASSERT(expr) ((void) 0)
216 : #define PR_NOT_REACHED(reasonStr)
217 :
218 : #endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
219 :
220 : PR_END_EXTERN_C
221 :
222 : #endif /* prlog_h___ */
|
