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