OSX/libsecurity_asn1/lib/prlog.h

   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 <security_asn1/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(NDEBUG) || defined(FORCE_PR_ASSERT)
 236
 237 #ifdef  __APPLE__
 238
 239 #include <assert.h>
 240
 241 #define PR_ASSERT(_exp)                 assert(_exp)
 242 #define PR_NOT_REACHED(_reas)   assert(0)
 243
 244 #else
 245 NSPR_API(void) PR_Assert(const char *s, const char *file, PRIntn ln);
 246 #define PR_ASSERT(_expr) \
 247     ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
 248
 249 #define PR_NOT_REACHED(_reasonStr) \
 250     PR_Assert(_reasonStr,__FILE__,__LINE__)
 251 #endif
 252
 253 #else
 254
 255 #define PR_ASSERT(expr) ((void) 0)
 256 #define PR_NOT_REACHED(reasonStr)
 257
 258 #endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
 259
 260 PR_END_EXTERN_C
 261
 262 #endif /* prlog_h___ */