diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 09:22:09 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 09:22:09 +0000 |
commit | 43a97878ce14b72f0981164f87f2e35e14151312 (patch) | |
tree | 620249daf56c0258faa40cbdcf9cfba06de2a846 /docs/nspr/reference/logging.rst | |
parent | Initial commit. (diff) | |
download | firefox-43a97878ce14b72f0981164f87f2e35e14151312.tar.xz firefox-43a97878ce14b72f0981164f87f2e35e14151312.zip |
Adding upstream version 110.0.1.upstream/110.0.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/nspr/reference/logging.rst')
-rw-r--r-- | docs/nspr/reference/logging.rst | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/docs/nspr/reference/logging.rst b/docs/nspr/reference/logging.rst new file mode 100644 index 0000000000..ba91ad39a6 --- /dev/null +++ b/docs/nspr/reference/logging.rst @@ -0,0 +1,116 @@ +NSPR Logging +============ + +This chapter describes the global functions you use to perform logging. +NSPR provides a set of logging functions that conditionally write +``printf()`` style strings to the console or to a log file. NSPR uses +this facility itself for its own development debugging purposes. + +You can select events to be logged by module or level. A module is a +user-defined class of log events. A level is a numeric value that +indicates the seriousness of the event to be logged. You can combine +module and level criteria to get highly selective logging. + +NSPR also provides "assert"-style macros and functions to aid in +application debugging. + +- `Conditional Compilation and + Execution <#Conditional_Compilation_and_Execution>`__ +- `Log Types and Variables <#Log_Types_and_Variables>`__ +- `Logging Functions and Macros <#Logging_Functions_and_Macros>`__ +- `Use Example <#Use_Example>`__ + +.. _Conditional_Compilation_and_Execution: + +Conditional Compilation and Execution +------------------------------------- + +NSPR's logging facility is conditionally compiled in and enabled for +applications using it. These controls are platform dependent. Logging is +not compiled in for the Win16 platform. Logging is compiled into the +NSPR debug builds; logging is not compiled into the NSPR optimized +builds. The compile time ``#define`` values ``DEBUG`` or +``FORCE_PR_LOG`` enable NSPR logging for application programs. + +To enable NSPR logging and/or the debugging aids in your application, +compile using the NSPR debug build headers and runtime. Set one of the +compile-time defines when you build your application. + +Execution-time control of NSPR's logging uses two environment variables. +These variables control which modules and levels are logged as well as +the file name of the log file. By default, no logging is enabled at +execution time. + +.. _Log_Types_and_Variables: + +Log Types and Variables +----------------------- + +Two types supporting NSPR logging are exposed in the API: + + - :ref:`PRLogModuleInfo` + - :ref:`PRLogModuleLevel` + +Two environment variables control the behavior of logging at execution +time: + + - :ref:`NSPR_LOG_MODULES` + - :ref:`NSPR_LOG_FILE` + +.. _Logging_Functions_and_Macros: + +Logging Functions and Macros +---------------------------- + +The functions and macros for logging are: + + - :ref:`PR_NewLogModule` + - :ref:`PR_SetLogFile` + - :ref:`PR_SetLogBuffering` + - :ref:`PR_LogPrint` + - :ref:`PR_LogFlush` + - :ref:`PR_LOG_TEST` + - :ref:`PR_LOG` + - :ref:`PR_Assert` + - :ref:`PR_STATIC_ASSERT` (new in NSPR 4.6.6XXX this hasn't been released + yet; the number is a logical guess) + - :ref:`PR_NOT_REACHED` + +.. note:: + + The above documentation has not been ported to MDN yet, see + http://www-archive.mozilla.org/projects/nspr/reference/html/prlog.html#25338. + +.. _Use_Example: + +Use Example +----------- + +The following sample code fragment demonstrates use of the logging and +debugging aids. + +- Compile the program with DEBUG defined. +- Before running the compiled program, set the environment variable + NSPR_LOG_MODULES to userStuff:5 + +.. code:: + + static void UserLogStuff( void ) + { + PRLogModuleInfo *myLM; + PRIntn i; + + PR_STATIC_ASSERT(5 > 4); /* NSPR 4.6.6 or newer */ + + myLM = PR_NewLogModule( "userStuff" ); + PR_ASSERT( myLM ); + + PR_LOG( myLM, PR_LOG_NOTICE, ("Log a Notice %d\n", 999 )); + for (i = 0; i < 10 ; i++ ) + { + PR_LOG( myLM, PR_LOG_DEBUG, ("Log Debug number: %d\n", i)); + PR_Sleep( 500 ); + } + PR_LOG( myLM, PR_LOG_NOTICE, "That's all folks\n"); + + } /* end UserLogStuff() */ |