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
40PR_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
135typedef 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*/
153typedef struct PRLogModuleInfo {
154    const char *name;
155    PRLogModuleLevel level;
156    struct PRLogModuleInfo *next;
157} PRLogModuleInfo;
158
159/*
160** Create a new log module.
161*/
162NSPR_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*/
168NSPR_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*/
174NSPR_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*/
182NSPR_API(void) PR_LogPrint(const char *fmt, ...);
183
184/*
185** Flush the log to its file.
186*/
187NSPR_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
237NSPR_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
251PR_END_EXTERN_C
252
253#endif /* prlog_h___ */
254