summaryrefslogtreecommitdiffstats
path: root/docs/nspr/reference/logging.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
commit36d22d82aa202bb199967e9512281e9a53db42c9 (patch)
tree105e8c98ddea1c1e4784a60a5a6410fa416be2de /docs/nspr/reference/logging.rst
parentInitial commit. (diff)
downloadfirefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.tar.xz
firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.zip
Adding upstream version 115.7.0esr.upstream/115.7.0esr
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.rst116
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() */