Back to index

lightning-sunbird  0.9+nobinonly
prlog.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef prlog_h___
00039 #define prlog_h___
00040 
00041 #include "prtypes.h"
00042 
00043 PR_BEGIN_EXTERN_C
00044 
00045 /*
00046 ** prlog.h -- Declare interfaces to NSPR's Logging service
00047 **
00048 ** NSPR provides a logging service that is used by NSPR itself and is
00049 ** available to client programs.
00050 **
00051 ** To use the service from a client program, you should create a
00052 ** PRLogModuleInfo structure by calling PR_NewLogModule(). After
00053 ** creating the LogModule, you can write to the log using the PR_LOG()
00054 ** macro.
00055 **
00056 ** Initialization of the log service is handled by NSPR initialization.
00057 **
00058 ** At execution time, you must enable the log service. To enable the
00059 ** log service, set the environment variable: NSPR_LOG_MODULES
00060 ** variable.
00061 **
00062 ** NSPR_LOG_MODULES variable has the form:
00063 **
00064 **     <moduleName>:<value>[, <moduleName>:<value>]*
00065 **
00066 ** Where:
00067 **  <moduleName> is the name passed to PR_NewLogModule().
00068 **  <value> is a numeric constant, e.g. 5. This value is the maximum
00069 ** value of a log event, enumerated by PRLogModuleLevel, that you want
00070 ** written to the log.
00071 ** 
00072 ** For example: to record all events of greater value than or equal to
00073 ** PR_LOG_ERROR for a LogModule names "gizmo", say:
00074 ** 
00075 ** set NSPR_LOG_MODULES=gizmo:2
00076 ** 
00077 ** Note that you must specify the numeric value of PR_LOG_ERROR.
00078 ** 
00079 ** Special LogModule names are provided for controlling NSPR's log
00080 ** service at execution time. These controls should be set in the
00081 ** NSPR_LOG_MODULES environment variable at execution time to affect
00082 ** NSPR's log service for your application.
00083 ** 
00084 ** The special LogModule "all" enables all LogModules. To enable all
00085 ** LogModule calls to PR_LOG(), say:
00086 ** 
00087 ** set NSPR_LOG_MODULES=all:5
00088 ** 
00089 ** The special LogModule name "sync" tells the NSPR log service to do
00090 ** unbuffered logging.
00091 ** 
00092 ** The special LogModule name "bufsize:<size>" tells NSPR to set the
00093 ** log buffer to <size>.
00094 **
00095 ** The environment variable NSPR_LOG_FILE specifies the log file to use
00096 ** unless the default of "stderr" is acceptable. For MS Windows
00097 ** systems, NSPR_LOG_FILE can be set to a special value: "WinDebug"
00098 ** (case sensitive). This value causes PR_LOG() output to be written
00099 ** using the Windows API OutputDebugString(). OutputDebugString()
00100 ** writes to the debugger window; some people find this helpful.
00101 ** 
00102 **
00103 ** To put log messages in your programs, use the PR_LOG macro:
00104 **
00105 **     PR_LOG(<module>, <level>, (<printfString>, <args>*));
00106 **
00107 ** Where <module> is the address of a PRLogModuleInfo structure, and
00108 ** <level> is one of the levels defined by the enumeration:
00109 ** PRLogModuleLevel. <args> is a printf() style of argument list. That
00110 ** is: (fmtstring, ...).
00111 **
00112 ** Example:
00113 ** 
00114 ** main() {
00115 **    PRIntn one = 1;
00116 **    PRLogModuleInfo * myLm = PR_NewLogModule("gizmo");
00117 **    PR_LOG( myLm, PR_LOG_ALWAYS, ("Log this! %d\n", one)); 
00118 **    return; 
00119 ** }
00120 ** 
00121 ** Note the use of printf() style arguments as the third agrument(s) to
00122 ** PR_LOG().
00123 ** 
00124 ** After compiling and linking you application, set the environment:
00125 ** 
00126 ** set NSPR_LOG_MODULES=gizmo:5
00127 ** set NSPR_LOG_FILE=logfile.txt
00128 ** 
00129 ** When you execute your application, the string "Log this! 1" will be
00130 ** written to the file "logfile.txt".
00131 ** 
00132 ** Note to NSPR engineers: a number of PRLogModuleInfo structures are
00133 ** defined and initialized in prinit.c. See this module for ideas on
00134 ** what to log where.
00135 ** 
00136 */
00137 
00138 typedef enum PRLogModuleLevel {
00139     PR_LOG_NONE = 0,                /* nothing */
00140     PR_LOG_ALWAYS = 1,              /* always printed */
00141     PR_LOG_ERROR = 2,               /* error messages */
00142     PR_LOG_WARNING = 3,             /* warning messages */
00143     PR_LOG_DEBUG = 4,               /* debug messages */
00144 
00145     PR_LOG_NOTICE = PR_LOG_DEBUG,   /* notice messages */
00146     PR_LOG_WARN = PR_LOG_WARNING,   /* warning messages */
00147     PR_LOG_MIN = PR_LOG_DEBUG,      /* minimal debugging messages */
00148     PR_LOG_MAX = PR_LOG_DEBUG       /* maximal debugging messages */
00149 } PRLogModuleLevel;
00150 
00151 /*
00152 ** One of these structures is created for each module that uses logging.
00153 **    "name" is the name of the module
00154 **    "level" is the debugging level selected for that module
00155 */
00156 typedef struct PRLogModuleInfo {
00157     const char *name;
00158     PRLogModuleLevel level;
00159     struct PRLogModuleInfo *next;
00160 } PRLogModuleInfo;
00161 
00162 /*
00163 ** Create a new log module.
00164 */
00165 NSPR_API(PRLogModuleInfo*) PR_NewLogModule(const char *name);
00166 
00167 /*
00168 ** Set the file to use for logging. Returns PR_FALSE if the file cannot
00169 ** be created
00170 */
00171 NSPR_API(PRBool) PR_SetLogFile(const char *name);
00172 
00173 /*
00174 ** Set the size of the logging buffer. If "buffer_size" is zero then the
00175 ** logging becomes "synchronous" (or unbuffered).
00176 */
00177 NSPR_API(void) PR_SetLogBuffering(PRIntn buffer_size);
00178 
00179 /*
00180 ** Print a string to the log. "fmt" is a PR_snprintf format type. All
00181 ** messages printed to the log are preceeded by the name of the thread
00182 ** and a time stamp. Also, the routine provides a missing newline if one
00183 ** is not provided.
00184 */
00185 NSPR_API(void) PR_LogPrint(const char *fmt, ...);
00186 
00187 /*
00188 ** Flush the log to its file.
00189 */
00190 NSPR_API(void) PR_LogFlush(void);
00191 
00192 /*
00193 ** Windoze 16 can't support a large static string space for all of the
00194 ** various debugging strings so logging is not enabled for it.
00195 */
00196 #if (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16)
00197 #define PR_LOGGING 1
00198 
00199 #define PR_LOG_TEST(_module,_level) \
00200     ((_module)->level >= (_level))
00201 
00202 /*
00203 ** Log something.
00204 **    "module" is the address of a PRLogModuleInfo structure
00205 **    "level" is the desired logging level
00206 **    "args" is a variable length list of arguments to print, in the following
00207 **       format:  ("printf style format string", ...)
00208 */
00209 #define PR_LOG(_module,_level,_args)     \
00210     PR_BEGIN_MACRO             \
00211       if (PR_LOG_TEST(_module,_level)) { \
00212       PR_LogPrint _args;         \
00213       }                     \
00214     PR_END_MACRO
00215 
00216 #else /* (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16) */
00217 
00218 #undef PR_LOGGING
00219 #define PR_LOG_TEST(module,level) 0
00220 #define PR_LOG(module,level,args)
00221 
00222 #endif /* (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16) */
00223 
00224 #ifndef NO_NSPR_10_SUPPORT
00225 
00226 #ifdef PR_LOGGING
00227 #define PR_LOG_BEGIN    PR_LOG
00228 #define PR_LOG_END      PR_LOG
00229 #define PR_LOG_DEFINE   PR_NewLogModule
00230 #else
00231 #define PR_LOG_BEGIN(module,level,args)
00232 #define PR_LOG_END(module,level,args)
00233 #define PR_LOG_DEFINE(_name)    NULL
00234 #endif /* PR_LOGGING */
00235 
00236 #endif /* NO_NSPR_10_SUPPORT */
00237 
00238 #if defined(DEBUG) || defined(FORCE_PR_ASSERT)
00239 
00240 NSPR_API(void) PR_Assert(const char *s, const char *file, PRIntn ln);
00241 #define PR_ASSERT(_expr) \
00242     ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
00243 
00244 #define PR_NOT_REACHED(_reasonStr) \
00245     PR_Assert(_reasonStr,__FILE__,__LINE__)
00246 
00247 #else
00248 
00249 #define PR_ASSERT(expr) ((void) 0)
00250 #define PR_NOT_REACHED(reasonStr)
00251 
00252 #endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
00253 
00254 PR_END_EXTERN_C
00255 
00256 #endif /* prlog_h___ */