Merge pull request #6083 from grom72/logging7md

doc: logging information added to manpages (7)

doc/libpmem/libpmem.7.md

@@ -19,7 +19,8 @@ header: "pmem API version 1.1"
 [CAVEATS](#caveats)<br />
 [LIBRARY API VERSIONING](#library-api-versioning-1)<br />
 [ENVIRONMENT](#environment)<br />
-[DEBUGGING AND ERROR HANDLING](#debugging-and-error-handling)<br />
+[ERROR HANDLING](#error-handling)<br />
+[DEBUGGING](#debugging)<br />
 [EXAMPLE](#example)<br />
 [ACKNOWLEDGEMENTS](#acknowledgements)<br />
 [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,

doc/libpmemobj/libpmemobj.7.md

@@ -18,7 +18,8 @@ header: "pmemobj API version 2.3"
 [DESCRIPTION](#description)<br />
 [LIBRARY API VERSIONING](#library-api-versioning-1)<br />
 [MANAGING LIBRARY BEHAVIOR](#managing-library-behavior-1)<br />
-[DEBUGGING AND ERROR HANDLING](#debugging-and-error-handling)<br />
+[ERROR HANDLING](#error-handling)<br />
+[DEBUGGING](#debugging)<br />
 [EXAMPLE](#example)<br />
 [ACKNOWLEDGEMENTS](#acknowledgements)<br />
 [SEE ALSO](#see-also)<br />
@@ -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.