Merge pull request #6043 from osalyk/logging_doc

doc: logging function documentation

doc/Makefile

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2014-2023, Intel Corporation
+# Copyright 2014-2024, Intel Corporation
 #
 
 #
@@ -18,6 +18,7 @@ MANPAGES_3_MD = libpmem/pmem_flush.3.md libpmem/pmem_is_pmem.3.md libpmem/pmem_m
 		libpmemobj/pmemobj_list_insert.3.md libpmemobj/pmemobj_memcpy_persist.3.md libpmemobj/pmemobj_mutex_zero.3.md \
 		libpmemobj/pmemobj_open.3.md libpmemobj/pmemobj_root.3.md libpmemobj/pmemobj_tx_begin.3.md libpmemobj/pmemobj_tx_add_range.3.md \
 		libpmemobj/pmemobj_tx_alloc.3.md libpmemobj/pobj_layout_begin.3.md libpmemobj/pobj_list_head.3.md libpmemobj/toid_declare.3.md \
+		libpmemobj/pmemobj_log_get_threshold.3.md libpmemobj/pmemobj_log_set_function.3.md libpmemobj/pmemobj_log_set_threshold.3.md \
 		libpmempool/pmempool_check_init.3.md libpmempool/pmempool_feature_query.3.md libpmempool/pmempool_rm.3.md libpmempool/pmempool_sync.3.md
 
 MANPAGES_1_MD = pmempool/pmempool.1.md pmempool/pmempool-info.1.md pmempool/pmempool-create.1.md \

doc/libpmemobj/.gitignore

@@ -5,6 +5,9 @@ pmemobj_alloc.3
 pmemobj_ctl_get.3
 pmemobj_first.3
 pmemobj_list_insert.3
+pmemobj_log_get_threshold.3
+pmemobj_log_set_function.3
+pmemobj_log_set_threshold.3
 pmemobj_memcpy_persist.3
 pmemobj_mutex_zero.3
 pmemobj_open.3

doc/libpmemobj/pmemobj_log_get_threshold.3.md

@@ -0,0 +1,56 @@
+---
+draft: false
+slider_enable: true
+description: ""
+disclaimer: "The contents of this web site and the associated <a href=\"https://github.com/pmem\">GitHub repositories</a> are BSD-licensed open source."
+aliases: ["pmemobj_log_get_threshold.3.html"]
+title: "libpmemobj | PMDK"
+header: "pmemobj API version 2.3"
+---
+
+[comment]: <> (SPDX-License-Identifier: BSD-3-Clause)
+[comment]: <> (Copyright 2024, Intel Corporation)
+
+[comment]: <> (pmemobj_log_get_threshold.3 -- get the logging threshold value)
+
+[NAME](#name)<br />
+[SYNOPSIS](#synopsis)<br />
+[DESCRIPTION](#description)<br />
+[RETURN VALUE](#return-value)<br />
+[ERRORS](#errors)<br />
+[SEE ALSO](#see-also)<br />
+
+# NAME #
+
+**pmemobj_log_get_threshold** - get the logging threshold value
+
+# SYNOPSIS #
+
+```c
+	#include <libpmemobj.h>
+
+	int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,
+		enum pmemobj_log_level *value);
+```
+
+# DESCRIPTION #
+
+**pmemobj_log_get_threshold**() gets the current *value* of the *threshold*.
+See **pmemobj_log_set_threshold**(3) for available thresholds and values.
+
+# RETURN VALUE #
+
+On success, **pmemobj_log_get_threshold**() function returns 0 and writes into
+*value* the current value of the *threshold*. On failure, it returns
+a non-zero value and sets errno. In case of failure, the *value* contents is undefined.
+
+# ERRORS #
+
+**pmemobj_log_get_threshold**() can fail with the following errors:
+
+ - EINVAL - *threshold* is not **PMEMOBJ_LOG_THRESHOLD** nor **PMEMOBJ_LOG_THRESHOLD_AUX**
+ - EINVAL - *value* is NULL
+
+# SEE ALSO #
+
+**pmemobj_log_set_function**(3), **pmemobj_log_set_threshold**(3).

doc/libpmemobj/pmemobj_log_set_function.3.md

@@ -0,0 +1,109 @@
+---
+draft: false
+slider_enable: true
+description: ""
+disclaimer: "The contents of this web site and the associated <a href=\"https://github.com/pmem\">GitHub repositories</a> are BSD-licensed open source."
+aliases: ["pmemobj_log_set_function.3.html"]
+title: "libpmemobj | PMDK"
+header: "pmemobj API version 2.3"
+---
+
+[comment]: <> (SPDX-License-Identifier: BSD-3-Clause)
+[comment]: <> (Copyright 2024, Intel Corporation)
+
+[comment]: <> (pmemobj_log_set_function.3 -- set the logging function)
+
+[NAME](#name)<br />
+[SYNOPSIS](#synopsis)<br />
+[DESCRIPTION](#description)<br />
+[THE DEFAULT LOGGING FUNCTION](#the-default-logging-function)<br />
+[RETURN VALUE](#return-value)<br />
+[ERRORS](#errors)<br />
+[NOTE](#note)<br />
+[SEE ALSO](#see-also)<br />
+
+# NAME #
+
+**pmemobj_log_set_function**() - set the logging function
+
+# SYNOPSIS #
+
+```c
+	#include <libpmemobj.h>
+
+	typedef void pmemobj_log_function(
+		enum pmemobj_log_level level,
+		const char *file_name,
+		const int line_no,
+		const char *function_name,
+		const char *message);
+
+	int pmemobj_log_set_function(pmemobj_log_function *log_function);
+```
+
+# DESCRIPTION #
+
+**pmemobj_log_set_function**() allows choosing the function which will get all
+the generated logging messages. The *log_function* can be either
+**PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** which will use the default logging function
+(built into the library) or a pointer to a user-defined function.
+
+The parameters of a user-defined log function are as follows:
+
+ - *level* - the log level of the message (see **pmemobj_log_set_threshold**(3)
+   for available log levels)
+ - *file_name* - name of the source file where the message is coming from.
+   It could be set to NULL and in such case, neither *line_no* nor *function_name*
+   are provided.
+ - *line_no* - the source file line where the message is coming from
+ - *function_name* - the function name where the message is coming from
+ - *message* - the message string
+
+# THE DEFAULT LOGGING FUNCTION #
+
+The library provides the default logging function which writes messages to
+**syslog**(3) and to **stderr**(3). This function is enabled during library
+initialization and can be restored using **PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** value
+as the *log_function* argument.
+
+The default logging function sinks all the logging messages into **syslog**(3)
+unconditionally. Additionally, it sinks a logging message into **stderr**(3)
+if its logging level is not less severe than indicated by
+the **PMEMOBJ_LOG_THRESHOLD_AUX** threshold's value and it is not of level
+**PMEMOBJ_LOG_LEVEL_HARK**.
+
+Note that the **PMEMOBJ_LOG_THRESHOLD** threshold's value applies to
+the default logging function. Please see the notes below.
+
+# RETURN VALUE #
+
+**pmemobj_log_set_function**() function returns 0 on success or returns
+a non-zero value and sets errno on failure. On failure, the logging
+function remains unchanged.
+
+# ERRORS #
+
+**pmemobj_log_set_function**() can set the following errno values on fail:
+
+ - EAGAIN - multiple threads attempted to change the logging function concurrently.
+   A retry may fix the problem. This error is not expected when the function is
+   called from just one thread at a time.
+
+# NOTE #
+
+The logging messages of level less severe than indicated by
+the **PMEMOBJ_LOG_THRESHOLD** threshold's value won't make it to the logging function
+no matter whether the logging function is the default logging function or user-provided.
+
+The user-defined function must be thread-safe.
+
+The library will call user defined function before returning from **pmemobj_log_set_function**()
+to deliver basic information about the library:
+
+ - "src version: 2.y.z"
+ - "compiled with support for shutdown state"
+ - "compiled with libndctl 63+"
+
+# SEE ALSO #
+
+**pmemobj_log_get_threshold**(3), **pmemobj_log_set_threshold**(3).

doc/libpmemobj/pmemobj_log_set_threshold.3.md

@@ -0,0 +1,104 @@
+---
+draft: false
+slider_enable: true
+description: ""
+disclaimer: "The contents of this web site and the associated <a href=\"https://github.com/pmem\">GitHub repositories</a> are BSD-licensed open source."
+aliases: ["pmemobj_log_set_threshold.3.html"]
+title: "libpmemobj | PMDK"
+header: "pmemobj API version 2.3"
+---
+
+[comment]: <> (SPDX-License-Identifier: BSD-3-Clause)
+[comment]: <> (Copyright 2024, Intel Corporation)
+
+[comment]: <> (pmemobj_log_set_threshold.3 -- set the logging threshold value)
+
+[NAME](#name)<br />
+[SYNOPSIS](#synopsis)<br />
+[DESCRIPTION](#description)<br />
+[RETURN VALUE](#return-value)<br />
+[ERRORS](#errors)<br />
+[SEE ALSO](#see-also)<br />
+
+# NAME #
+
+**pmemobj_log_set_threshold** - set the logging threshold value
+
+# SYNOPSIS #
+
+```c
+	#include <libpmemobj.h>
+
+	enum pmemobj_log_level {
+		PMEMOBJ_LOG_LEVEL_HARK,
+		PMEMOBJ_LOG_LEVEL_FATAL,
+		PMEMOBJ_LOG_LEVEL_ERROR,
+		PMEMOBJ_LOG_LEVEL_WARNING,
+		PMEMOBJ_LOG_LEVEL_NOTICE,
+		PMEMOBJ_LOG_LEVEL_INFO,
+		PMEMOBJ_LOG_LEVEL_DEBUG
+	};
+
+	enum pmemobj_log_threshold {
+		PMEMOBJ_LOG_THRESHOLD,
+		PMEMOBJ_LOG_THRESHOLD_AUX
+	};
+
+	int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold,
+		enum pmemobj_log_level value);
+```
+
+# DESCRIPTION #
+
+**pmemobj_log_set_threshold**() sets the logging threshold value.
+
+Available thresholds are:
+
+ - **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesired
+  logging messages. Messages less severe than indicated by this threshold's
+  value are ignored so they won't make it to the logging function
+  (please see **pmemobj_log_set_function**(3)).
+  The default value is **PMEMOBJ_LOG_WARNING**.
+ - **PMEMOBJ_LOG_THRESHOLD_AUX** - the auxiliary threshold intended for use inside
+  the logging function (please see **pmemobj_log_get_threshold**(3)). A custom
+  logging function may or may not take this threshold into consideration depending
+  on the developer's needs. For the default logging function behaviour please see
+  **pmemobj_log_set_function**(3). The initial value of this threshold is
+  **PMEMOBJ_LOG_LEVEL_HARK**.
+
+Available threshold values are defined by enum *pmemobj_log_level*.
+They are listed in descending order of severity:
+
+ - **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info. Shall be used to
+   effectively suppress the logging since it is used just for a few messages
+   when the program is started and whenever a new logging function is set.
+   Please see **pmemobj_log_set_function**(3).
+ - **PMEMOBJ_LOG_LEVEL_FATAL** - an error that causes the program to stop working
+   immediately. Sorry.
+ - **PMEMOBJ_LOG_LEVEL_ERROR** - an error that causes the current operation or transaction to fail
+ - **PMEMOBJ_LOG_LEVEL_WARNING** - an unexpected situation that does NOT
+   cause the current operation to fail
+ - **PMEMOBJ_LOG_LEVEL_NOTICE** - non-massive info mainly related to public API
+   function completions
+ - **PMEMOBJ_LOG_LEVEL_INFO** - massive info e.g. every write operation indication
+ - **PMEMOBJ_LOG_LEVEL_DEBUG** - debug info e.g. write operation dump
+
+# RETURN VALUE #
+
+**pmemobj_log_set_threshold**() function returns 0 on success or returns
+a non-zero value and sets errno on failure. On failure, the *threshold* value remains unchanged.
+
+# ERRORS #
+
+**pmemobj_log_set_threshold**() can set the following errno values on fail:
+
+ - EINVAL - *threshold* is not **PMEMOBJ_LOG_THRESHOLD** nor
+   **PMEMOBJ_LOG_THRESHOLD_AUX**
+ - EINVAL - *value* is not defined by enum *pmemobj_log_level* type
+ - EAGAIN - multiple threads attempted to change the *threshold* value concurrently.
+   A retry may fix the problem. This error is not expected when the function is
+   called from just one thread at a time.
+
+# SEE ALSO #
+
+**pmemobj_log_get_threshold**(3), **pmemobj_log_set_function**(3).