From 0c3223ee6f22c84cf12fb3c3997001fc455c63d8 Mon Sep 17 00:00:00 2001 From: "Gromadzki, Tomasz" Date: Tue, 7 May 2024 20:43:16 +0200 Subject: [PATCH] doc: logging information added to manpages (7) Signed-off-by: Tomasz Gromadzki [LIBRARY API VERSIONING](#library-api-versioning-1)
[ENVIRONMENT](#environment)
-[DEBUGGING AND ERROR HANDLING](#debugging-and-error-handling)
+[ERROR HANDLING](#error-handling)
+[DEBUGGING](#debugging)
[EXAMPLE](#example)
[ACKNOWLEDGEMENTS](#acknowledgements)
[SEE ALSO](#see-also) @@ -223,7 +224,7 @@ affects all the PMDK libraries,** disabling mapping address randomization and causing the specified address to be used as a hint about where to place the mapping. -# DEBUGGING AND ERROR HANDLING # +# ERROR HANDLING # If an error is detected during the call to a **libpmem** function, the application may retrieve an error message describing the reason of the failure @@ -238,6 +239,14 @@ call to a **libpmem** function indicated an error. The application must not modify or free the error message string. Subsequent calls to other library functions may modify the previous message. +In parallel to the above mechanism, all logging messages are written to +**syslog**(3) and/or **stderr**(3) or passed to the user-provided logging +function. Please see **pmem_log_set_function**(3) for details. +The influx of the reported messages can be controlled by setting a respective +threshold value. Please see **pmem_log_set_threshold**(3) for details. + +# DEBBUGING # + Two versions of **libpmem** are typically available on a development system. The normal version, accessed when a program is linked using the **-lpmem** option, is optimized for performance. That version skips checks @@ -253,8 +262,8 @@ variables. These variables have no effect on the non-debug version of the librar + **PMEM_LOG_LEVEL** -The value of **PMEM_LOG_LEVEL** enables trace points in the debug version -of the library, as follows: +The value of the **PMEM_LOG_LEVEL** environment variable enables trace points in +the debug version of the library, as follows: + **0** - This is the default level when **PMEM_LOG_LEVEL** is not set. No log messages are emitted at this level. @@ -271,7 +280,8 @@ library. + **4** - Enables voluminous and fairly obscure tracing information that is likely only useful to the **libpmem** developers. -Unless **PMEM_LOG_FILE** is set, debugging output is written to *stderr*. +Unless the **PMEM_LOG_FILE** environment variable is set, the debugging output +is written to *stderr*. + **PMEM_LOG_FILE** @@ -281,6 +291,11 @@ is "-", the *PID* of the current process will be appended to the file name when the log file is created. If **PMEM_LOG_FILE** is not set, output is written to *stderr*. +Whenever either **PMEM_LOG_LEVEL** or **PMEM_LOG_FILE** environment variable is +set the messages are not passed via the routes described in +the [ERROR HANDLING](#error-handling) section except for the **pmem_errormsg**() +which works unconditionally. + # EXAMPLE # The following example uses **libpmem** to flush changes made to raw, diff --git a/doc/libpmemobj/libpmemobj.7.md b/doc/libpmemobj/libpmemobj.7.md index 3c089ae708c..8fdb6b69d6a 100644 --- a/doc/libpmemobj/libpmemobj.7.md +++ b/doc/libpmemobj/libpmemobj.7.md @@ -18,7 +18,8 @@ header: "pmemobj API version 2.3" [DESCRIPTION](#description)
[LIBRARY API VERSIONING](#library-api-versioning-1)
[MANAGING LIBRARY BEHAVIOR](#managing-library-behavior-1)
-[DEBUGGING AND ERROR HANDLING](#debugging-and-error-handling)
+[ERROR HANDLING](#error-handling)
+[DEBUGGING](#debugging)
[EXAMPLE](#example)
[ACKNOWLEDGEMENTS](#acknowledgements)
[SEE ALSO](#see-also)
@@ -162,7 +163,7 @@ transactions/allocations. For debugging purposes it is possible to decrease this value by setting the **PMEMOBJ_NLANES** environment variable to the desired limit. -# DEBUGGING AND ERROR HANDLING # +# ERROR HANDLING # If an error is detected during the call to a **libpmemobj** function, the application may retrieve an error message describing the reason for the failure @@ -177,6 +178,14 @@ call to a **libpmemobj** function indicated an error, or if *errno* was set. The application must not modify or free the error message string, but it may be modified by subsequent calls to other library functions. +In parallel to the above mechanism, all logging messages are written to +**syslog**(3) and/or **stderr**(3) or passed to the user-provided logging +function. Please see **pmemobj_log_set_function**(3) for details. +The influx of the reported messages can be controlled by setting a respective +threshold value. Please see **pmemobj_log_set_threshold**(3) for details. + +# DEBBUGING # + Two versions of **libpmemobj** are typically available on a development system. The normal version, accessed when a program is linked using the **-lpmemobj** option, is optimized for performance. That version skips checks @@ -192,8 +201,8 @@ variables. These variables have no effect on the non-debug version of the librar + **PMEMOBJ_LOG_LEVEL** -The value of **PMEMOBJ_LOG_LEVEL** enables trace points in the debug version -of the library, as follows: +The value of the **PMEMOBJ_LOG_LEVEL** environment variable enables trace points +in the debug version of the library, as follows: + **0** - This is the default level when **PMEMOBJ_LOG_LEVEL** is not set. No log messages are emitted at this level. @@ -210,7 +219,8 @@ tracing in the library. + **4** - Enables voluminous and fairly obscure tracing information that is likely only useful to the **libpmemobj** developers. -Unless **PMEMOBJ_LOG_FILE** is set, debugging output is written to *stderr*. +Unless the **PMEMOBJ_LOG_FILE** environment variable is set, the debugging +output is written to *stderr*. + **PMEMOBJ_LOG_FILE** @@ -219,6 +229,11 @@ If the last character in the name is "-", the *PID* of the current process will be appended to the file name when the log file is created. If **PMEMOBJ_LOG_FILE** is not set, logging output is written to *stderr*. +Whenever either **PMEMOBJ_LOG_LEVEL** or **PMEMOBJ_LOG_FILE** environment +variable is set the messages are not passed via the routes described in +the [ERROR HANDLING](#error-handling) section except for +the **pmemobj_errormsg**() which works unconditionally. + See also **libpmem**(7) to get information about other environment variables affecting **libpmemobj** behavior.