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
11PR_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
106typedef 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*/
124typedef struct PRLogModuleInfo {
125 const char *name;
126 PRLogModuleLevel level;
127 struct PRLogModuleInfo *next;
128} PRLogModuleInfo;
129
130/*
131** Create a new log module.
132*/
133NSPR_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*/
139NSPR_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*/
145NSPR_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*/
153NSPR_API(void) PR_LogPrint(const char *fmt, ...);
154
155/*
156** Flush the log to its file.
157*/
158NSPR_API(void) PR_LogFlush(void);
159
160NSPR_API(void) PR_Assert(const char *s, const char *file, PRIntn ln)
161PR_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
224PR_END_EXTERN_C
225
226#endif /* prlog_h___ */
227

source code of include/nspr/prlog.h