diff --git a/doc/Makefile b/doc/Makefile index 764a1409c03..ec541ebfb56 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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 \ @@ -64,7 +65,8 @@ MANPAGES_3_DUMMY = libpmem/pmem_drain.3 libpmem/pmem_has_hw_drain.3 libpmem/pmem libpmemobj/pmemobj_check_version.3 libpmemobj/pmemobj_check.3 libpmemobj/pmemobj_errormsg.3 libpmemobj/pmemobj_set_funcs.3 \ libpmemobj/pmemobj_reserve.3 libpmemobj/pmemobj_xreserve.3 libpmemobj/pmemobj_defer_free.3 libpmemobj/pmemobj_set_value.3 libpmemobj/pmemobj_publish.3 libpmemobj/pmemobj_tx_publish.3 libpmemobj/pmemobj_tx_xpublish.3 libpmemobj/pmemobj_cancel.3 libpmemobj/pobj_reserve_new.3 libpmemobj/pobj_reserve_alloc.3 libpmemobj/pobj_xreserve_new.3 libpmemobj/pobj_xreserve_alloc.3 \ libpmemobj/tx_xstrdup.3 libpmemobj/tx_xwcsdup.3 libpmemobj/tx_xfree.3 \ - libpmemobj/pmemobj_defrag.3 libpmemobj/pmemobj_get_user_data.3 libpmemobj/pmemobj_set_user_data.3 libpmemobj/pmemobj_tx_get_user_data.3 libpmemobj/pmemobj_tx_set_user_data.3 libpmemobj/pmemobj_tx_get_failure_behavior.3 libpmemobj/pmemobj_tx_set_failure_behavior.3 + libpmemobj/pmemobj_defrag.3 libpmemobj/pmemobj_get_user_data.3 libpmemobj/pmemobj_set_user_data.3 libpmemobj/pmemobj_tx_get_user_data.3 libpmemobj/pmemobj_tx_set_user_data.3 libpmemobj/pmemobj_tx_get_failure_behavior.3 libpmemobj/pmemobj_tx_set_failure_behavior.3 \ + libpmemobj/pmemobj_log_get_threshold.3.md libpmemobj/pmemobj_log_set_function.3.md libpmemobj/pmemobj_log_set_threshold.3.md MANPAGES_WEBDIR_LINUX = web_linux 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..32cbbce5001 --- /dev/null +++ b/doc/libpmemobj/pmemobj_log_get_threshold.3.md @@ -0,0 +1,52 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pobj_log_get_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_get_threshold.3 -- man page for get the logging threshold level) + +[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 level + +# SYNOPSIS # + +```c + int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, + enum pmemobj_log_levellevel); +``` + +# 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). \ No newline at end of file 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..c3ceaa38895 --- /dev/null +++ b/doc/libpmemobj/pmemobj_log_set_function.3.md @@ -0,0 +1,84 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pobj_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 -- man page for set the logging function) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[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_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). \ No newline at end of file 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..f8d3bc5664d --- /dev/null +++ b/doc/libpmemobj/pmemobj_log_set_threshold.3.md @@ -0,0 +1,101 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pobj_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_threshold.3 -- man page for set the logging threshold level) + +[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 level + + # SYNOPSIS # + +```c +#include + + 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). \ No newline at end of file