logging.rst (3604B)
1 NSPR Logging 2 ============ 3 4 This chapter describes the global functions you use to perform logging. 5 NSPR provides a set of logging functions that conditionally write 6 ``printf()`` style strings to the console or to a log file. NSPR uses 7 this facility itself for its own development debugging purposes. 8 9 You can select events to be logged by module or level. A module is a 10 user-defined class of log events. A level is a numeric value that 11 indicates the seriousness of the event to be logged. You can combine 12 module and level criteria to get highly selective logging. 13 14 NSPR also provides "assert"-style macros and functions to aid in 15 application debugging. 16 17 - `Conditional Compilation and 18 Execution <#Conditional_Compilation_and_Execution>`__ 19 - `Log Types and Variables <#Log_Types_and_Variables>`__ 20 - `Logging Functions and Macros <#Logging_Functions_and_Macros>`__ 21 - `Use Example <#Use_Example>`__ 22 23 .. _Conditional_Compilation_and_Execution: 24 25 Conditional Compilation and Execution 26 ------------------------------------- 27 28 NSPR's logging facility is conditionally compiled in and enabled for 29 applications using it. These controls are platform dependent. Logging is 30 not compiled in for the Win16 platform. Logging is compiled into the 31 NSPR debug builds; logging is not compiled into the NSPR optimized 32 builds. The compile time ``#define`` values ``DEBUG`` or 33 ``FORCE_PR_LOG`` enable NSPR logging for application programs. 34 35 To enable NSPR logging and/or the debugging aids in your application, 36 compile using the NSPR debug build headers and runtime. Set one of the 37 compile-time defines when you build your application. 38 39 Execution-time control of NSPR's logging uses two environment variables. 40 These variables control which modules and levels are logged as well as 41 the file name of the log file. By default, no logging is enabled at 42 execution time. 43 44 .. _Log_Types_and_Variables: 45 46 Log Types and Variables 47 ----------------------- 48 49 Two types supporting NSPR logging are exposed in the API: 50 51 - :ref:`PRLogModuleInfo` 52 - :ref:`PRLogModuleLevel` 53 54 Two environment variables control the behavior of logging at execution 55 time: 56 57 - :ref:`NSPR_LOG_MODULES` 58 - :ref:`NSPR_LOG_FILE` 59 60 .. _Logging_Functions_and_Macros: 61 62 Logging Functions and Macros 63 ---------------------------- 64 65 The functions and macros for logging are: 66 67 - :ref:`PR_NewLogModule` 68 - :ref:`PR_SetLogFile` 69 - :ref:`PR_SetLogBuffering` 70 - :ref:`PR_LogPrint` 71 - :ref:`PR_LogFlush` 72 - :ref:`PR_LOG_TEST` 73 - :ref:`PR_LOG` 74 - :ref:`PR_Assert` 75 - :ref:`PR_STATIC_ASSERT` (new in NSPR 4.6.6XXX this hasn't been released 76 yet; the number is a logical guess) 77 - :ref:`PR_NOT_REACHED` 78 79 .. note:: 80 81 The above documentation has not been ported to MDN yet, see 82 http://www-archive.mozilla.org/projects/nspr/reference/html/prlog.html#25338. 83 84 .. _Use_Example: 85 86 Use Example 87 ----------- 88 89 The following sample code fragment demonstrates use of the logging and 90 debugging aids. 91 92 - Compile the program with DEBUG defined. 93 - Before running the compiled program, set the environment variable 94 NSPR_LOG_MODULES to userStuff:5 95 96 .. code:: 97 98 static void UserLogStuff( void ) 99 { 100 PRLogModuleInfo *myLM; 101 PRIntn i; 102 103 PR_STATIC_ASSERT(5 > 4); /* NSPR 4.6.6 or newer */ 104 105 myLM = PR_NewLogModule( "userStuff" ); 106 PR_ASSERT( myLM ); 107 108 PR_LOG( myLM, PR_LOG_NOTICE, ("Log a Notice %d\n", 999 )); 109 for (i = 0; i < 10 ; i++ ) 110 { 111 PR_LOG( myLM, PR_LOG_DEBUG, ("Log Debug number: %d\n", i)); 112 PR_Sleep( 500 ); 113 } 114 PR_LOG( myLM, PR_LOG_NOTICE, "That's all folks\n"); 115 116 } /* end UserLogStuff() */