From e3be5fc286f68d6664d22965ecdce31669be8b7d Mon Sep 17 00:00:00 2001 From: Oksana Salyk Date: Fri, 8 Mar 2024 14:37:40 +0100 Subject: [PATCH] doc: logging function documentation --- doc/Makefile | 3 +- doc/libpmemobj/.gitignore | 3 + doc/libpmemobj/pmemobj_log_get_threshold.3.md | 56 +++++++ doc/libpmemobj/pmemobj_log_set_function.3.md | 99 ++++++++++++ doc/libpmemobj/pmemobj_log_set_threshold.3.md | 104 +++++++++++++ src/include/libpmemobj/log.h | 146 +----------------- 6 files changed, 268 insertions(+), 143 deletions(-) create mode 100644 doc/libpmemobj/pmemobj_log_get_threshold.3.md create mode 100644 doc/libpmemobj/pmemobj_log_set_function.3.md create mode 100644 doc/libpmemobj/pmemobj_log_set_threshold.3.md diff --git a/doc/Makefile b/doc/Makefile index 764a1409c03..48f5b37d030 100644 --- a/doc/Makefile +++ b/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 \ diff --git a/doc/libpmemobj/.gitignore b/doc/libpmemobj/.gitignore index 19523dae4f9..f0e1a6f0f43 100644 --- a/doc/libpmemobj/.gitignore +++ b/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 diff --git a/doc/libpmemobj/pmemobj_log_get_threshold.3.md b/doc/libpmemobj/pmemobj_log_get_threshold.3.md new file mode 100644 index 00000000000..397dc9b82f4 --- /dev/null +++ b/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 GitHub repositories 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)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_log_get_threshold** - get the logging threshold value + +# SYNOPSIS # + +```c + #include + + 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 # + +**pmemobj_log_get_threshold**() function returns 0 and sets the *threshold* value +on success. On failure, it returns a non-zero value and sets errno. +In case of failure, the *threshold* value 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). diff --git a/doc/libpmemobj/pmemobj_log_set_function.3.md b/doc/libpmemobj/pmemobj_log_set_function.3.md new file mode 100644 index 00000000000..c6a2476afd8 --- /dev/null +++ b/doc/libpmemobj/pmemobj_log_set_function.3.md @@ -0,0 +1,99 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories 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)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[THE DEFAULT LOGGING FUNCTION](#the-default-logging-function)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[NOTE](#note)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_log_set_function**() - set the logging function + +# SYNOPSIS # + +```c + #include + + 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)) +- *file_name* - name of the source file where the message 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 coming from + - *function_name* - the function name where the message coming from + - *message* - the message string + +# THE DEFAULT LOGGING FUNCTION # + +The library provides the default logging function which writes messages to +**syslog**(3) (the primary destination) and to **stderr**(3) (the secondary +destination). This function is enabled during library initialization and can +be restored using **PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** value as the *log_function* +argument. + +# 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 on the levels above the **PMEMOBJ_LOG_THRESHOLD** level won't +trigger the logging function. + +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). diff --git a/doc/libpmemobj/pmemobj_log_set_threshold.3.md b/doc/libpmemobj/pmemobj_log_set_threshold.3.md new file mode 100644 index 00000000000..8ab2415a2e1 --- /dev/null +++ b/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 GitHub repositories 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)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_log_set_threshold** - set the logging threshold value + +# SYNOPSIS # + +```c + #include + + 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, + PMEMOBJ_LOG_THRESHOLD_MAX, + }; + + 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 on a higher level than the primary threshold + value are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress + logging except for the basic library info. Please see the + **PMEMOBJ_LOG_LEVEL_HARK** for details. + 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*: + + - **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info. 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). diff --git a/src/include/libpmemobj/log.h b/src/include/libpmemobj/log.h index 43c0eaaecfe..caa7abf7d48 100644 --- a/src/include/libpmemobj/log.h +++ b/src/include/libpmemobj/log.h @@ -49,105 +49,16 @@ enum pmemobj_log_threshold { }; /* - * pmemobj_log_set_threshold - set the logging threshold level - * - * SYNOPSIS - * - * int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold, - * enum pmemobj_log_level level); - * - * enum 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 log_threshold { - * PMEMOBJ_LOG_THRESHOLD, - * PMEMOBJ_LOG_THRESHOLD_AUX, - * PMEMOBJ_LOG_THRESHOLD_MAX - * }; - * - * DESCRIPTION - * pmemobj_log_set_threshold() sets the logging threshold level. - * - * Available thresholds are: - * - PMEMOBJ_LOG_THRESHOLD - the main threshold used to filter out undesired - * logging messages. Messages on a higher level than the primary threshold - * level are ignored. PMEMOBJ_LOG_LEVEL_HARK shall be used to suppress - * logging. - * The default value is PMEMOBJ_LOG_WARNING. - * - PMEMOBJ_LOG_THRESHOLD_AUX - the auxiliary threshold intended for use inside - * the logging function (please see log_get_threshold(3)). The logging - * function may or may not take this threshold into consideration. The default - * value is PMEMOBJ_LOG_LEVEL_HARK. - * - * Available threshold levels are defined by enum log_level: - * - PMEMOBJ_LOG_LEVEL_HARK - only basic library info - * - PMEMOBJ_LOG_LEVEL_FATAL - an error that causes the library to stop working - * immediately - * - PMEMOBJ_LOG_LEVEL_ERROR - an error that causes the library to stop working - * properly - * - PMEMOBJ_LOG_LEVEL_WARNING - an error that could be handled in the upper - * level - * - 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 - * - * THE DEFAULT LOGGING FUNCTION - * The default logging function writes messages to syslog(3) and to stderr(3), - * where syslog(3) is the primary destination (PMEMOBJ_LOG_THRESHOLD applies) - * whereas stderr(3) is the secondary destination (PMEMOBJ_LOG_THRESHOLD_AUX - * applies). - * - * RETURN VALUE - * pmemobj_log_set_threshold() function returns 0 on success or returns - * a non-zero value and sets errno on failure. - * - * 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 - level is not a value defined by enum log_level type - * - EAGAIN - a temporary error occurred, the retry may fix the problem - * - * SEE ALSO - * pmemobj_log_get_threshold(3), pmemobj_log_set_function(3). + * pmemobj_log_set_threshold - set the logging threshold value */ int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold, - enum pmemobj_log_level level); + enum pmemobj_log_level value); /* - * pmemobj_log_get_threshold - get the logging threshold level - * - * SYNOPSIS - * - * int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, - * enum pmemobj_log_level *level); - * - * DESCRIPTION - * pmemobj_log_get_threshold() gets the current level of the threshold. - * See pmemobj_log_set_threshold(3) for available thresholds and levels. - * - * RETURN VALUE - * pmemobj_log_get_threshold() function returns 0 on success or returns - * a non-zero value and sets errno on failure. - * - * ERRORS - * pmemobj_log_get_threshold() can fail with the following errors: - * - EINVAL - threshold is not CORE_LOG_THRESHOLD nor CORE_LOG_THRESHOLD_AUX - * - EINVAL - *level is NULL - * - * SEE ALSO - * pmemobj_log_set_function(3), pmemobj_log_set_threshold(3). + * pmemobj_log_get_threshold - get the logging threshold value */ int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, - enum pmemobj_log_level *level); + enum pmemobj_log_level *value); /* * the type used for defining logging functions @@ -170,55 +81,6 @@ typedef void pmemobj_log_function( /* * pmemobj_log_set_function - set the logging function - * - * SYNOPSIS - * - * 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_format, - * ...); - * - * 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. - * - * Parameters of a user-defined log function are as follow: - * - level - the log level of the message - * - file_name - name of the source file where the message 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 coming from - * - function_name - the function name where the message coming from - * - message_format - printf(3)-like format string of the message - * - "..." - additional arguments of the message format string - * - * THE DEFAULT LOGGING FUNCTION - * The initial value of the logging function is CORE_LOG_USE_DEFAULT_FUNCTION. - * This function writes messages to syslog(3) (the primary destination) and to - * stderr(3) (the secondary destination). - * - * RETURN VALUE - * pmemobj_log_set_function() function returns 0 on success or returns - * a non-zero value and sets errno on failure. - * - * ERRORS - * - EAGAIN - a temporary error occurred, the retry may fix the problem - * - * NOTE - * The logging messages on the levels above the CORE_LOG_THRESHOLD level won't - * trigger the logging function. - * - * The user defined function must be thread-safe. - * - * SEE ALSO - * pmemobj_log_get_threshold(3), pmemobj_log_set_threshold(3). */ int pmemobj_log_set_function(pmemobj_log_function *log_function);