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..ae4651be666 --- /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: ["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 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_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). \ 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..207f20fd87b --- /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: ["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)
+[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..c112838353b --- /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: ["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 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 diff --git a/src/include/libpmemobj/log.h b/src/include/libpmemobj/log.h index 43c0eaaecfe..fc69fa09b7c 100644 --- a/src/include/libpmemobj/log.h +++ b/src/include/libpmemobj/log.h @@ -50,101 +50,12 @@ 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). */ int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level level); /* * 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). */ int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level); @@ -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);