1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prlog.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,221 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prlog_h___
1.10 +#define prlog_h___
1.11 +
1.12 +#include "prtypes.h"
1.13 +
1.14 +PR_BEGIN_EXTERN_C
1.15 +
1.16 +/*
1.17 +** prlog.h -- Declare interfaces to NSPR's Logging service
1.18 +**
1.19 +** NSPR provides a logging service that is used by NSPR itself and is
1.20 +** available to client programs.
1.21 +**
1.22 +** To use the service from a client program, you should create a
1.23 +** PRLogModuleInfo structure by calling PR_NewLogModule(). After
1.24 +** creating the LogModule, you can write to the log using the PR_LOG()
1.25 +** macro.
1.26 +**
1.27 +** Initialization of the log service is handled by NSPR initialization.
1.28 +**
1.29 +** At execution time, you must enable the log service. To enable the
1.30 +** log service, set the environment variable: NSPR_LOG_MODULES
1.31 +** variable.
1.32 +**
1.33 +** NSPR_LOG_MODULES variable has the form:
1.34 +**
1.35 +** <moduleName>:<value>[, <moduleName>:<value>]*
1.36 +**
1.37 +** Where:
1.38 +** <moduleName> is the name passed to PR_NewLogModule().
1.39 +** <value> is a numeric constant, e.g. 5. This value is the maximum
1.40 +** value of a log event, enumerated by PRLogModuleLevel, that you want
1.41 +** written to the log.
1.42 +**
1.43 +** For example: to record all events of greater value than or equal to
1.44 +** PR_LOG_ERROR for a LogModule names "gizmo", say:
1.45 +**
1.46 +** set NSPR_LOG_MODULES=gizmo:2
1.47 +**
1.48 +** Note that you must specify the numeric value of PR_LOG_ERROR.
1.49 +**
1.50 +** Special LogModule names are provided for controlling NSPR's log
1.51 +** service at execution time. These controls should be set in the
1.52 +** NSPR_LOG_MODULES environment variable at execution time to affect
1.53 +** NSPR's log service for your application.
1.54 +**
1.55 +** The special LogModule "all" enables all LogModules. To enable all
1.56 +** LogModule calls to PR_LOG(), say:
1.57 +**
1.58 +** set NSPR_LOG_MODULES=all:5
1.59 +**
1.60 +** The special LogModule name "sync" tells the NSPR log service to do
1.61 +** unbuffered logging.
1.62 +**
1.63 +** The special LogModule name "bufsize:<size>" tells NSPR to set the
1.64 +** log buffer to <size>.
1.65 +**
1.66 +** The environment variable NSPR_LOG_FILE specifies the log file to use
1.67 +** unless the default of "stderr" is acceptable. For MS Windows
1.68 +** systems, NSPR_LOG_FILE can be set to a special value: "WinDebug"
1.69 +** (case sensitive). This value causes PR_LOG() output to be written
1.70 +** using the Windows API OutputDebugString(). OutputDebugString()
1.71 +** writes to the debugger window; some people find this helpful.
1.72 +**
1.73 +**
1.74 +** To put log messages in your programs, use the PR_LOG macro:
1.75 +**
1.76 +** PR_LOG(<module>, <level>, (<printfString>, <args>*));
1.77 +**
1.78 +** Where <module> is the address of a PRLogModuleInfo structure, and
1.79 +** <level> is one of the levels defined by the enumeration:
1.80 +** PRLogModuleLevel. <args> is a printf() style of argument list. That
1.81 +** is: (fmtstring, ...).
1.82 +**
1.83 +** Example:
1.84 +**
1.85 +** main() {
1.86 +** PRIntn one = 1;
1.87 +** PRLogModuleInfo * myLm = PR_NewLogModule("gizmo");
1.88 +** PR_LOG( myLm, PR_LOG_ALWAYS, ("Log this! %d\n", one));
1.89 +** return;
1.90 +** }
1.91 +**
1.92 +** Note the use of printf() style arguments as the third agrument(s) to
1.93 +** PR_LOG().
1.94 +**
1.95 +** After compiling and linking you application, set the environment:
1.96 +**
1.97 +** set NSPR_LOG_MODULES=gizmo:5
1.98 +** set NSPR_LOG_FILE=logfile.txt
1.99 +**
1.100 +** When you execute your application, the string "Log this! 1" will be
1.101 +** written to the file "logfile.txt".
1.102 +**
1.103 +** Note to NSPR engineers: a number of PRLogModuleInfo structures are
1.104 +** defined and initialized in prinit.c. See this module for ideas on
1.105 +** what to log where.
1.106 +**
1.107 +*/
1.108 +
1.109 +typedef enum PRLogModuleLevel {
1.110 + PR_LOG_NONE = 0, /* nothing */
1.111 + PR_LOG_ALWAYS = 1, /* always printed */
1.112 + PR_LOG_ERROR = 2, /* error messages */
1.113 + PR_LOG_WARNING = 3, /* warning messages */
1.114 + PR_LOG_DEBUG = 4, /* debug messages */
1.115 +
1.116 + PR_LOG_NOTICE = PR_LOG_DEBUG, /* notice messages */
1.117 + PR_LOG_WARN = PR_LOG_WARNING, /* warning messages */
1.118 + PR_LOG_MIN = PR_LOG_DEBUG, /* minimal debugging messages */
1.119 + PR_LOG_MAX = PR_LOG_DEBUG /* maximal debugging messages */
1.120 +} PRLogModuleLevel;
1.121 +
1.122 +/*
1.123 +** One of these structures is created for each module that uses logging.
1.124 +** "name" is the name of the module
1.125 +** "level" is the debugging level selected for that module
1.126 +*/
1.127 +typedef struct PRLogModuleInfo {
1.128 + const char *name;
1.129 + PRLogModuleLevel level;
1.130 + struct PRLogModuleInfo *next;
1.131 +} PRLogModuleInfo;
1.132 +
1.133 +/*
1.134 +** Create a new log module.
1.135 +*/
1.136 +NSPR_API(PRLogModuleInfo*) PR_NewLogModule(const char *name);
1.137 +
1.138 +/*
1.139 +** Set the file to use for logging. Returns PR_FALSE if the file cannot
1.140 +** be created
1.141 +*/
1.142 +NSPR_API(PRBool) PR_SetLogFile(const char *name);
1.143 +
1.144 +/*
1.145 +** Set the size of the logging buffer. If "buffer_size" is zero then the
1.146 +** logging becomes "synchronous" (or unbuffered).
1.147 +*/
1.148 +NSPR_API(void) PR_SetLogBuffering(PRIntn buffer_size);
1.149 +
1.150 +/*
1.151 +** Print a string to the log. "fmt" is a PR_snprintf format type. All
1.152 +** messages printed to the log are preceeded by the name of the thread
1.153 +** and a time stamp. Also, the routine provides a missing newline if one
1.154 +** is not provided.
1.155 +*/
1.156 +NSPR_API(void) PR_LogPrint(const char *fmt, ...);
1.157 +
1.158 +/*
1.159 +** Flush the log to its file.
1.160 +*/
1.161 +NSPR_API(void) PR_LogFlush(void);
1.162 +
1.163 +NSPR_API(void) PR_Assert(const char *s, const char *file, PRIntn ln);
1.164 +
1.165 +#if defined(DEBUG) || defined(FORCE_PR_LOG)
1.166 +#define PR_LOGGING 1
1.167 +
1.168 +#define PR_LOG_TEST(_module,_level) \
1.169 + ((_module)->level >= (_level))
1.170 +
1.171 +/*
1.172 +** Log something.
1.173 +** "module" is the address of a PRLogModuleInfo structure
1.174 +** "level" is the desired logging level
1.175 +** "args" is a variable length list of arguments to print, in the following
1.176 +** format: ("printf style format string", ...)
1.177 +*/
1.178 +#define PR_LOG(_module,_level,_args) \
1.179 + PR_BEGIN_MACRO \
1.180 + if (PR_LOG_TEST(_module,_level)) { \
1.181 + PR_LogPrint _args; \
1.182 + } \
1.183 + PR_END_MACRO
1.184 +
1.185 +#else /* defined(DEBUG) || defined(FORCE_PR_LOG) */
1.186 +
1.187 +#undef PR_LOGGING
1.188 +#define PR_LOG_TEST(module,level) 0
1.189 +#define PR_LOG(module,level,args)
1.190 +
1.191 +#endif /* defined(DEBUG) || defined(FORCE_PR_LOG) */
1.192 +
1.193 +#ifndef NO_NSPR_10_SUPPORT
1.194 +
1.195 +#ifdef PR_LOGGING
1.196 +#define PR_LOG_BEGIN PR_LOG
1.197 +#define PR_LOG_END PR_LOG
1.198 +#define PR_LOG_DEFINE PR_NewLogModule
1.199 +#else
1.200 +#define PR_LOG_BEGIN(module,level,args)
1.201 +#define PR_LOG_END(module,level,args)
1.202 +#define PR_LOG_DEFINE(_name) NULL
1.203 +#endif /* PR_LOGGING */
1.204 +
1.205 +#endif /* NO_NSPR_10_SUPPORT */
1.206 +
1.207 +#if defined(DEBUG) || defined(FORCE_PR_ASSERT)
1.208 +
1.209 +#define PR_ASSERT(_expr) \
1.210 + ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
1.211 +
1.212 +#define PR_NOT_REACHED(_reasonStr) \
1.213 + PR_Assert(_reasonStr,__FILE__,__LINE__)
1.214 +
1.215 +#else
1.216 +
1.217 +#define PR_ASSERT(expr) ((void) 0)
1.218 +#define PR_NOT_REACHED(reasonStr)
1.219 +
1.220 +#endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
1.221 +
1.222 +PR_END_EXTERN_C
1.223 +
1.224 +#endif /* prlog_h___ */
