From e4e1e7ae5108251b22de1c27327e175ad87d8acd Mon Sep 17 00:00:00 2001 From: pmem-bot Date: Thu, 31 Aug 2023 11:49:24 +0000 Subject: [PATCH] pmdk: automatic docs update for 'stable-2.0' --- .../pmdk/manpages/linux/v2.0/daxio/daxio.1.md | 109 ++++ .../manpages/linux/v2.0/libpmem/libpmem.7.md | 358 ++++++++++++ .../linux/v2.0/libpmem/pmem_flush.3.md | 197 +++++++ .../linux/v2.0/libpmem/pmem_is_pmem.3.md | 160 +++++ .../v2.0/libpmem/pmem_memmove_persist.3.md | 149 +++++ .../linux/v2.0/libpmem2/libpmem2.7.md | 301 ++++++++++ .../libpmem2/libpmem2_unsafe_shutdown.7.md | 85 +++ .../v2.0/libpmem2/pmem2_badblock_clear.3.md | 77 +++ .../libpmem2/pmem2_badblock_context_new.3.md | 116 ++++ .../v2.0/libpmem2/pmem2_badblock_next.3.md | 63 ++ .../linux/v2.0/libpmem2/pmem2_config_new.3.md | 63 ++ .../libpmem2/pmem2_config_set_length.3.md | 52 ++ .../libpmem2/pmem2_config_set_offset.3.md | 61 ++ .../libpmem2/pmem2_config_set_protection.3.md | 77 +++ ...config_set_required_store_granularity.3.md | 71 +++ .../libpmem2/pmem2_config_set_sharing.3.md | 65 +++ .../pmem2_config_set_vm_reservation.3.md | 51 ++ .../linux/v2.0/libpmem2/pmem2_deep_flush.3.md | 68 +++ .../linux/v2.0/libpmem2/pmem2_errormsg.3.md | 55 ++ .../v2.0/libpmem2/pmem2_get_drain_fn.3.md | 62 ++ .../v2.0/libpmem2/pmem2_get_flush_fn.3.md | 75 +++ .../v2.0/libpmem2/pmem2_get_memmove_fn.3.md | 146 +++++ .../v2.0/libpmem2/pmem2_get_persist_fn.3.md | 100 ++++ .../linux/v2.0/libpmem2/pmem2_map_delete.3.md | 66 +++ .../libpmem2/pmem2_map_from_existing.3.md | 64 ++ .../v2.0/libpmem2/pmem2_map_get_address.3.md | 46 ++ .../v2.0/libpmem2/pmem2_map_get_size.3.md | 46 ++ .../pmem2_map_get_store_granularity.3.md | 54 ++ .../linux/v2.0/libpmem2/pmem2_map_new.3.md | 125 ++++ .../linux/v2.0/libpmem2/pmem2_perror.3.md | 45 ++ .../v2.0/libpmem2/pmem2_source_alignment.3.md | 76 +++ .../v2.0/libpmem2/pmem2_source_device_id.3.md | 77 +++ .../libpmem2/pmem2_source_device_usc.3.md | 71 +++ .../v2.0/libpmem2/pmem2_source_from_anon.3.md | 64 ++ .../v2.0/libpmem2/pmem2_source_from_fd.3.md | 75 +++ .../v2.0/libpmem2/pmem2_source_get_fd.3.md | 56 ++ .../v2.0/libpmem2/pmem2_source_numa_node.3.md | 70 +++ .../libpmem2/pmem2_source_pread_mcsafe.3.md | 83 +++ .../v2.0/libpmem2/pmem2_source_size.3.md | 84 +++ .../libpmem2/pmem2_vm_reservation_extend.3.md | 98 ++++ .../pmem2_vm_reservation_get_address.3.md | 47 ++ .../pmem2_vm_reservation_get_size.3.md | 46 ++ .../pmem2_vm_reservation_map_find.3.md | 88 +++ .../libpmem2/pmem2_vm_reservation_new.3.md | 96 +++ .../linux/v2.0/libpmemobj/libpmemobj.7.md | 237 ++++++++ .../linux/v2.0/libpmemobj/oid_is_null.3.md | 189 ++++++ .../linux/v2.0/libpmemobj/pmemobj_action.3.md | 191 ++++++ .../linux/v2.0/libpmemobj/pmemobj_alloc.3.md | 280 +++++++++ .../v2.0/libpmemobj/pmemobj_ctl_get.3.md | 421 ++++++++++++++ .../linux/v2.0/libpmemobj/pmemobj_first.3.md | 104 ++++ .../v2.0/libpmemobj/pmemobj_list_insert.3.md | 164 ++++++ .../libpmemobj/pmemobj_memcpy_persist.3.md | 186 ++++++ .../v2.0/libpmemobj/pmemobj_mutex_zero.3.md | 195 +++++++ .../linux/v2.0/libpmemobj/pmemobj_open.3.md | 169 ++++++ .../linux/v2.0/libpmemobj/pmemobj_root.3.md | 98 ++++ .../v2.0/libpmemobj/pmemobj_tx_add_range.3.md | 194 +++++++ .../v2.0/libpmemobj/pmemobj_tx_alloc.3.md | 260 +++++++++ .../v2.0/libpmemobj/pmemobj_tx_begin.3.md | 548 ++++++++++++++++++ .../v2.0/libpmemobj/pobj_layout_begin.3.md | 105 ++++ .../linux/v2.0/libpmemobj/pobj_list_head.3.md | 252 ++++++++ .../linux/v2.0/libpmemobj/toid_declare.3.md | 110 ++++ .../linux/v2.0/libpmempool/libpmempool.7.md | 268 +++++++++ .../v2.0/libpmempool/pmempool_check_init.3.md | 208 +++++++ .../libpmempool/pmempool_feature_query.3.md | 100 ++++ .../linux/v2.0/libpmempool/pmempool_rm.3.md | 55 ++ .../linux/v2.0/libpmempool/pmempool_sync.3.md | 135 +++++ .../linux/v2.0/pmem_ctl/pmem_ctl.5.md | 126 ++++ .../linux/v2.0/pmempool/pmempool-check.1.md | 100 ++++ .../linux/v2.0/pmempool/pmempool-convert.1.md | 27 + .../linux/v2.0/pmempool/pmempool-create.1.md | 119 ++++ .../linux/v2.0/pmempool/pmempool-dump.1.md | 93 +++ .../linux/v2.0/pmempool/pmempool-feature.1.md | 123 ++++ .../linux/v2.0/pmempool/pmempool-info.1.md | 295 ++++++++++ .../linux/v2.0/pmempool/pmempool-rm.1.md | 96 +++ .../linux/v2.0/pmempool/pmempool-sync.1.md | 95 +++ .../v2.0/pmempool/pmempool-transform.1.md | 138 +++++ .../linux/v2.0/pmempool/pmempool.1.md | 128 ++++ .../linux/v2.0/pmreorder/pmreorder.1.md | 424 ++++++++++++++ .../manpages/linux/v2.0/poolset/poolset.5.md | 230 ++++++++ 79 files changed, 10501 insertions(+) create mode 100644 content/pmdk/manpages/linux/v2.0/daxio/daxio.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem/libpmem.7.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem/pmem_flush.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem/pmem_is_pmem.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem/pmem_memmove_persist.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2.7.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2_unsafe_shutdown.7.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_clear.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_context_new.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_next.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_new.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_length.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_offset.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_protection.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_required_store_granularity.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_sharing.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_vm_reservation.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_deep_flush.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_errormsg.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_drain_fn.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_flush_fn.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_memmove_fn.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_persist_fn.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_delete.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_from_existing.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_address.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_size.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_store_granularity.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_new.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_perror.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_alignment.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_id.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_usc.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_anon.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_fd.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_get_fd.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_numa_node.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_pread_mcsafe.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_size.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_extend.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_address.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_size.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_map_find.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_new.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/libpmemobj.7.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/oid_is_null.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_action.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_alloc.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_ctl_get.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_first.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_list_insert.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_memcpy_persist.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_mutex_zero.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_open.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_root.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_add_range.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_alloc.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_begin.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_layout_begin.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_list_head.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmemobj/toid_declare.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmempool/libpmempool.7.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_check_init.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_feature_query.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_rm.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_sync.3.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmem_ctl/pmem_ctl.5.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-check.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-convert.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-create.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-dump.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-feature.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-info.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-rm.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-sync.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool-transform.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmempool/pmempool.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/pmreorder/pmreorder.1.md create mode 100644 content/pmdk/manpages/linux/v2.0/poolset/poolset.5.md diff --git a/content/pmdk/manpages/linux/v2.0/daxio/daxio.1.md b/content/pmdk/manpages/linux/v2.0/daxio/daxio.1.md new file mode 100644 index 0000000000..a1c43e2d90 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/daxio/daxio.1.md @@ -0,0 +1,109 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["daxio.1.html"] +title: "daxio | PMDK" +header: "daxio version 1.4" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2018, Intel Corporation) + +[comment]: <> (daxio.1 -- man page for daxio) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[OPTIONS](#options)
+[EXAMPLE](#example)
+[SEE ALSO](#see-also)
+ +# NAME # + +**daxio** - Perform I/O on Device DAX devices or zero a Device DAX device + +# SYNOPSIS # + +``` +$ daxio [] +``` + +# DESCRIPTION # + +The daxio utility performs I/O on Device DAX devices or zero +a Device DAX device. Since the standard I/O APIs (read/write) cannot be used +with Device DAX, data transfer is performed on a memory-mapped device. +The **daxio** may be used to dump Device DAX data to a file, restore data from +a backup copy, move/copy data to another device or to erase data from +a device. + +There must be at least one Device DAX device involved either as the input +or output. If input or output is not specified, it will default to stdin +or stdout respectively. + +No length specified will default to input file/device length or to the +output file/device length, if input is a special char file or stdin. + +For a Device DAX device, **daxio** will attempt to clear bad blocks within +the range of writes before performing the I/O (it can be turned off using +the '--clear-bad-blocks=no' option). + +# OPTIONS # + +`-i, --input` +Input device or file to read from. + +`-o, --output` +Output device or file to write to. + +`-z, --zero` +Zero the output device for *len* size, or the entire device if no +length was provided. The output device must be a Device DAX device. + +`-b, --clear-bad-blocks=` +Clear bad blocks within the range of writes before performing the I/O +(default: yes). + +`-l, --len` +The length in bytes to perform the I/O. To make passing in size easier +for kibi, mebi, gibi, and tebi bytes, *len* may include unit suffix. +The *len* format must be compliant with the format specified in IEC 80000-13, +IEEE 1541 or the Metric Interchange Format. These standards accept SI units +with obligatory B - kB, MB, GB, ... (multiplier by 1000) suffixes, +and IEC units with optional "iB" - KiB, MiB, GiB, ..., K, M, G, ... +(multiplier by 1024) suffixes. + +`-s, --seek` +The number of bytes to skip over on the output before performing a write. +The same suffixes are accepted as for *len*. + +`-k, --skip` +The number of bytes to skip over on the input before performing a read. +The same suffixes are accepted as for *len*. + +`-V, --version` + +Prints the version of **daxio**. + +`-h, --help` + +Prints synopsis and list of options. + +# EXAMPLE # + +``` +# daxio --zero /dev/dax1.0 + +# daxio --input=/dev/dax1.0 --output=/home/myfile --len=2M --seek=4096 + +# cat /dev/zero | daxio --output=/dev/dax1.0 + +# daxio --input=/dev/zero --output=/dev/dax1.0 --skip=4096 +``` + +# SEE ALSO # + +**daxctl**(1), **ndctl**(1) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem/libpmem.7.md b/content/pmdk/manpages/linux/v2.0/libpmem/libpmem.7.md new file mode 100644 index 0000000000..b64454422e --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem/libpmem.7.md @@ -0,0 +1,358 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["libpmem.7.html"] +title: "libpmem | PMDK" +header: "pmem API version 1.1" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2018, Intel Corporation) + +[comment]: <> (libpmem.7 -- man page for libpmem) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[CAVEATS](#caveats)
+[LIBRARY API VERSIONING](#library-api-versioning-1)
+[ENVIRONMENT](#environment)
+[DEBUGGING AND ERROR HANDLING](#debugging-and-error-handling)
+[EXAMPLE](#example)
+[ACKNOWLEDGEMENTS](#acknowledgements)
+[SEE ALSO](#see-also) + +# NAME # + +**libpmem** - persistent memory support library + +# SYNOPSIS # + +```c +#include +cc ... -lpmem +``` + +##### Library API versioning: ##### + +```c +const char *pmem_check_version( + unsigned major_required, + unsigned minor_required); +``` + +##### Error handling: ##### + +```c +const char *pmem_errormsg(void); +``` + +##### Other library functions: ##### + +A description of other **libpmem** functions can be found on the following +manual pages: + ++ most commonly used functions: **pmem_is_pmem**(3) + ++ partial flushing operations: **pmem_flush**(3) + ++ copying to persistent memory: **pmem_memmove_persist**(3) + +# DESCRIPTION # + +**libpmem** provides low-level *persistent memory* (pmem) support for +applications using direct access storage (DAX), which is storage that +supports load/store access without paging blocks from a block storage +device. Some types of *non-volatile memory DIMMs* (NVDIMMs) provide this +type of byte addressable access to storage. A *persistent memory aware +file system* is typically used to expose the direct access to +applications. Memory mapping a file from this type of file system +results in the load/store, non-paged access to pmem. + +This library is for applications that use persistent memory directly, +without the help of any library-supplied transactions or memory +allocation. A higher-level library that relies on **libpmem** is available +and recommended for most applications, see: + ++ **libpmemobj**(7), a general use persistent memory API, providing memory + allocation and transactional operations on variable-sized objects. + +Under normal usage, **libpmem** will never print messages or +intentionally cause the process to exit. +The only exception to this is the debugging information, when enabled, +as described under **DEBUGGING AND ERROR HANDLING** below. + +# CAVEATS # + +**libpmem** relies on the library destructor being called from the main thread. +For this reason, all functions that might trigger destruction (e.g. +**dlclose**(3)) should be called in the main thread. Otherwise some of the +resources associated with that thread might not be cleaned up properly. + +# LIBRARY API VERSIONING # + +This section describes how the library API is versioned, allowing +applications to work with an evolving API. + +The **pmem_check_version**() function is used to determine whether the installed +**libpmem** supports the version of the library API required by an +application. The easiest way to do this is for the application to supply +the compile-time version information, supplied by defines in +**\**, like this: + +```c +reason = pmem_check_version(PMEM_MAJOR_VERSION, PMEM_MINOR_VERSION); +if (reason != NULL) { + /* version check failed, reason string tells you why */ +} +``` + +Any mismatch in the major version number is considered a failure, but a +library with a newer minor version number will pass this check since +increasing minor versions imply backwards compatibility. + +An application can also check specifically for the existence of an +interface by checking for the version where that interface was +introduced. These versions are documented in this man page as follows: +unless otherwise specified, all interfaces described here are available +in version 1.0 of the library. Interfaces added after version 1.0 will +contain the text *introduced in version x.y* in the section of this +manual describing the feature. + +When the version check performed by **pmem_check_version**() is +successful, the return value is NULL. Otherwise the return value is a +static string describing the reason for failing the version check. The +string returned by **pmem_check_version**() must not be modified or +freed. + +# ENVIRONMENT # + +**libpmem** can change its default behavior based on the following +environment variables. These are largely intended for testing and are +not normally required. + ++ **PMEM_IS_PMEM_FORCE**=*val* + +If *val* is 0 (zero), then **pmem_is_pmem**(3) will always return +false. Setting *val* to 1 causes **pmem_is_pmem**(3) to always return +true. This variable is mostly used for testing but can be used to force +pmem behavior on a system where a range of pmem is not detectable as +pmem for some reason. + +>NOTE: +Unlike the other variables, the value of +**PMEM_IS_PMEM_FORCE** is not queried (and cached) at +library initialization time, but on the first call to +**pmem_is_pmem**(3). This means that in case of **libpmemobj**(7), +**PMEM_IS_PMEM_FORCE** may still be set or modified by the program +until the first attempt to create or open the persistent +memory pool. + ++ **PMEM_NO_CLWB**=1 + +Setting this environment variable to 1 forces **libpmem** to never issue +the **CLWB** instruction on Intel hardware, falling back to other cache +flush instructions instead (**CLFLUSHOPT** or **CLFLUSH** on Intel +hardware). Without this environment variable, **libpmem** will always +use the **CLWB** instruction for flushing processor caches on platforms +that support the instruction. This variable is intended for use during +library testing but may be required for some rare cases where using +**CLWB** has a negative impact on performance. + ++ **PMEM_NO_CLFLUSHOPT**=1 + +Setting this environment variable to 1 forces **libpmem** to never issue +the **CLFLUSHOPT** instruction on Intel hardware, falling back to the +**CLFLUSH** instructions instead. Without this environment variable, +**libpmem** will always use the **CLFLUSHOPT** instruction for flushing +processor caches on platforms that support the instruction, but where +**CLWB** is not available. This variable is intended for use during +library testing. + ++ **PMEM_NO_FLUSH**=1 + +Setting this environment variable to 1 forces most **libpmem** functions +to never issue any of **CLFLUSH**, **CLFLUSHOPT** or **CLWB** instructions +on Intel hardware. The only exceptions are **pmem_deep_flush**(3) and +**pmem_deep_persist**(3) functions. + ++ **PMEM_NO_FLUSH**=0 + +Setting this environment variable to 0 forces to always flush CPU caches +using one of **CLFLUSH**, **CLFLUSHOPT** or **CLWB** instructions +even if **pmem_has_auto_flush**(3) function returns true and the platform +supports flushing the processor caches on power loss or system crash. + ++ **PMEM_NO_MOVNT**=1 + +Setting this environment variable to 1 forces **libpmem** to never use +the *non-temporal* move instructions on Intel hardware. Without this +environment variable, **libpmem** will use the non-temporal instructions +for copying larger ranges to persistent memory on platforms that support +the instructions. This variable is intended for use during library +testing. + ++ **PMEM_MOVNT_THRESHOLD**=*val* + +This environment variable allows overriding the minimum length of +the **pmem_memmove_persist**(3) operations, for which **libpmem** uses +*non-temporal* move instructions. Setting this environment variable to 0 +forces **libpmem** to always use the *non-temporal* move instructions if +available. It has no effect if **PMEM_NO_MOVNT** is set to 1. +This variable is intended for use during library testing. + ++ **PMEM_MMAP_HINT**=*val* + +This environment variable allows overriding +the hint address used by **pmem_map_file**(). If set, it also disables +mapping address randomization. This variable is intended for use during +library testing and debugging. Setting it to some fairly large value +(i.e. 0x10000000000) will very likely result in mapping the file at the +specified address (if not used) or at the first unused region above +given address, without adding any random offset. When debugging, this +makes it easier to calculate the actual address of the persistent memory +block, based on its offset in the file. In case of **libpmemobj** it +simplifies conversion of a persistent object identifier (OID) into a +direct pointer to the object. + +>NOTE: +**Setting this environment variable +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 # + +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 +from **pmem_errormsg**(). This function returns a pointer to a static buffer +containing the last error message logged for the current thread. If *errno* +was set, the error message may include a description of the corresponding +error code as returned by **strerror**(3). The error message buffer is +thread-local; errors encountered in one thread do not affect its value in +other threads. The buffer is never cleared by any library function; its +content is significant only when the return value of the immediately preceding +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. + +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 +that impact performance and never logs any trace information or performs any +run-time assertions. + +A second version of **libpmem**, accessed when a program uses the libraries +under **/usr/lib/pmdk_debug**, contains run-time assertions and trace points. +The typical way to access the debug version is to set the environment variable +**LD_LIBRARY_PATH** to **/usr/lib/pmdk_debug** or **/usr/lib64/pmdk_debug**, +as appropriate. Debugging output is controlled using the following environment +variables. These variables have no effect on the non-debug version of the library. + ++ **PMEM_LOG_LEVEL** + +The value of **PMEM_LOG_LEVEL** 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. + ++ **1** - Additional details on any errors detected are logged, in addition +to returning the *errno*-based errors as usual. The same information +may be retrieved using **pmem_errormsg**(). + ++ **2** - A trace of basic operations is logged. + ++ **3** - Enables a very verbose amount of function call tracing in the +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*. + ++ **PMEM_LOG_FILE** + +Specifies the name of a file where +all logging information should be written. 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 **PMEM_LOG_FILE** is not set, output is +written to *stderr*. + +# EXAMPLE # + +The following example uses **libpmem** to flush changes made to raw, +memory-mapped persistent memory. + +>WARNING: +There is nothing transactional about the **pmem_persist**(3) or +**pmem_msync**(3) calls in this example. Interrupting the program may +result in a partial write to pmem. Use a transactional library such as +**libpmemobj**(7) to avoid torn updates. + +```c +#include +#include +#include +#include +#include +#include +#include +#include +#include + +/* using 4k of pmem for this example */ +#define PMEM_LEN 4096 + +#define PATH "/pmem-fs/myfile" + +int +main(int argc, char *argv[]) +{ + char *pmemaddr; + size_t mapped_len; + int is_pmem; + + /* create a pmem file and memory map it */ + + if ((pmemaddr = pmem_map_file(PATH, PMEM_LEN, PMEM_FILE_CREATE, + 0666, &mapped_len, &is_pmem)) == NULL) { + perror("pmem_map_file"); + exit(1); + } + + /* store a string to the persistent memory */ + strcpy(pmemaddr, "hello, persistent memory"); + + /* flush above strcpy to persistence */ + if (is_pmem) + pmem_persist(pmemaddr, mapped_len); + else + pmem_msync(pmemaddr, mapped_len); + + /* + * Delete the mappings. The region is also + * automatically unmapped when the process is + * terminated. + */ + pmem_unmap(pmemaddr, mapped_len); +} +``` + +See +for more examples using the **libpmem** API. + +# ACKNOWLEDGEMENTS # + +**libpmem** builds on the persistent memory programming model +recommended by the SNIA NVM Programming Technical Work Group: + + +# SEE ALSO # + +**dlclose**(3), +**pmem_flush**(3), **pmem_is_pmem**(3), **pmem_memmove_persist**(3), +**pmem_msync**(3), **pmem_persist**(3), **strerror**(3), +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem/pmem_flush.3.md b/content/pmdk/manpages/linux/v2.0/libpmem/pmem_flush.3.md new file mode 100644 index 0000000000..61e813b825 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem/pmem_flush.3.md @@ -0,0 +1,197 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem_flush.3.html"] +title: "libpmem | PMDK" +header: "pmem API version 1.1" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pmem_flush.3 -- man page for partial flushing operations + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem_flush**(), **pmem_drain**(), +**pmem_persist**(), **pmem_msync**(), +**pmem_deep_flush**(), **pmem_deep_drain**(), **pmem_deep_persist**(), +**pmem_has_hw_drain**(), **pmem_has_auto_flush**() - check persistency, + store persistent data and delete mappings + +# SYNOPSIS # + +```c +#include + +void pmem_persist(const void *addr, size_t len); +int pmem_msync(const void *addr, size_t len); +void pmem_flush(const void *addr, size_t len); +void pmem_deep_flush(const void *addr, size_t len); (EXPERIMENTAL) +int pmem_deep_drain(const void *addr, size_t len); (EXPERIMENTAL) +int pmem_deep_persist(const void *addr, size_t len); (EXPERIMENTAL) +void pmem_drain(void); +int pmem_has_auto_flush(void); (EXPERIMENTAL) +int pmem_has_hw_drain(void); +``` + +# DESCRIPTION # + +The functions in this section provide access to the stages of flushing +to persistence, for the less common cases where an application needs more +control of the flushing operations than the **pmem_persist**() function. + +>WARNING: +Using **pmem_persist**() on a range where **pmem_is_pmem**(3) +returns false may not do anything useful -- use **msync**(2) instead. + +The **pmem_persist**() function force any changes in the range +\[*addr*, *addr*+*len*) to be stored durably in +persistent memory. This is equivalent to calling **msync**(2) +but may be more optimal and will avoid calling into the kernel if +possible. There are no alignment restrictions on the range described by +*addr* and *len*, but **pmem_persist**() may expand the range as +necessary to meet platform alignment requirements. + +>WARNING: +Like **msync**(2), there is nothing atomic or transactional +about this call. Any unwritten stores in the given range will be +written, but some stores may have already been written by virtue of +normal cache eviction/replacement policies. Correctly written code must +not depend on stores waiting until **pmem_persist**() is called to +become persistent -- they can become persistent at any time before +**pmem_persist**() is called. + +The **pmem_msync**() function is like **pmem_persist**() in that it +forces any changes in the range \[*addr*, *addr*+*len*) to be stored +durably. Since it calls **msync**(), this function works on either +persistent memory or a memory mapped file on traditional storage. +**pmem_msync**() takes steps to ensure the alignment of addresses and +lengths passed to **msync**() meet the requirements of that system call. +It calls **msync**() with the **MS_SYNC** flag as described in +**msync**(2). Typically the application only checks for the existence of +persistent memory once, and then uses that result throughout the +program, for example: + +```c +/* do this call once, after the pmem is memory mapped */ +int is_pmem = pmem_is_pmem(rangeaddr, rangelen); + +/* ... make changes to a range of pmem ... */ + +/* make the changes durable */ +if (is_pmem) + pmem_persist(subrangeaddr, subrangelen); +else + pmem_msync(subrangeaddr, subrangelen); + +/* ... */ +``` + +>WARNING: +**pmem_msync**() and **msync**(2) have no effect on memory ranges +mapped from Device DAX. In case of memory ranges where **pmem_is_pmem**(3) +returns true use **pmem_persist**() to force the changes to be stored durably +in persistent memory. + +The **pmem_flush**() and **pmem_drain**() functions provide +partial versions of the **pmem_persist**() function. +**pmem_persist**() can be thought of as this: + +```c +void +pmem_persist(const void *addr, size_t len) +{ + /* flush the processor caches */ + pmem_flush(addr, len); + + /* wait for any pmem stores to drain from HW buffers */ + pmem_drain(); +} +``` + +These functions allow advanced programs to create their own variations +of **pmem_persist**(). For example, a program that needs to flush +several discontiguous ranges can call **pmem_flush**() for each range +and then follow up by calling **pmem_drain**() once. + +The semantics of **pmem_deep_flush**() function is the same as +**pmem_flush**() function except that **pmem_deep_flush**() is indifferent to +**PMEM_NO_FLUSH** environment variable (see **ENVIRONMENT** section in **libpmem**(7)) +and always flushes processor caches. + +The behavior of **pmem_deep_persist**() function is the same as **pmem_persist**(), +except that it provides higher reliability by flushing persistent memory stores to +the most reliable persistence domain available to software rather than depending on +automatic WPQ (write pending queue) flush on power failure (ADR). + +The **pmem_deep_flush**() and **pmem_deep_drain**() functions provide +partial versions of **pmem_deep_persist**() function. +**pmem_deep_persist**() can be thought of as this: + +``` +int pmem_deep_persist(const void *addr, size_t len) +{ + /* flush the processor caches */ + pmem_deep_flush(addr, len); + + /* wait for any pmem stores to drain from HW buffers */ + return pmem_deep_drain(addr, len); +} +``` + +Since this operation is usually much more expensive than **pmem_persist**(), +it should be used rarely. Typically the application should use this function +only to flush the most critical data, which are required to recover after +the power failure. + +The **pmem_has_auto_flush**() function checks if the machine supports automatic +CPU cache flush on power failure or system crash. +Function returns true only when each NVDIMM in the system is covered by this +mechanism. + +The **pmem_has_hw_drain**() function checks if the machine +supports an explicit *hardware drain* +instruction for persistent memory. + +# RETURN VALUE # + +The **pmem_persist**() function returns no value. + +The **pmem_msync**() return value is the return value of +**msync**(), which can return -1 and set *errno* to indicate an error. + +The **pmem_flush**(), **pmem_drain**() and **pmem_deep_flush**() +functions return no value. + +The **pmem_deep_persist**() and **pmem_deep_drain**() return 0 on success. +Otherwise it returns -1 and sets *errno* appropriately. If *len* is equal zero +**pmem_deep_persist**() and **pmem_deep_drain**() return 0 but no flushing take place. + +The **pmem_has_auto_flush**() function returns 1 if given platform supports +processor cache flushing on a power loss event. Otherwise it returns 0. +On error it returns -1 and sets *errno* appropriately. + +The **pmem_has_hw_drain**() function returns true if the machine +supports an explicit *hardware drain* +instruction for persistent memory. +On Intel processors with persistent memory, +stores to persistent memory are considered persistent +once they are flushed from the CPU caches, so this +function always returns false. Despite that, programs using +**pmem_flush**() to flush ranges of memory should still follow up by calling +**pmem_drain**() once to ensure the flushes are complete. As mentioned above, +**pmem_persist**() handles calling both **pmem_flush**() and **pmem_drain**(). + +# SEE ALSO # + +**msync**(2), **pmem_is_pmem**(3), **libpmem**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem/pmem_is_pmem.3.md b/content/pmdk/manpages/linux/v2.0/libpmem/pmem_is_pmem.3.md new file mode 100644 index 0000000000..4fa8bc045c --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem/pmem_is_pmem.3.md @@ -0,0 +1,160 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem_is_pmem.3.html"] +title: "libpmem | PMDK" +header: "pmem API version 1.1" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2023, Intel Corporation) + +[comment]: <> (pmem_is_pmem.3 -- man page for libpmem persistence and mapping functions) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[NOTES](#notes)
+[CAVEATS](#caveats)
+[BUGS](#bugs)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem_is_pmem**(), **pmem_map_file**(), +**pmem_unmap**() - check persistency, create and delete mappings + +# SYNOPSIS # + +```c +#include + +int pmem_is_pmem(const void *addr, size_t len); +void *pmem_map_file(const char *path, size_t len, int flags, mode_t mode, + size_t *mapped_lenp, int *is_pmemp); +int pmem_unmap(void *addr, size_t len); +``` + +# DESCRIPTION # + +Most pmem-aware applications will take advantage of higher level +libraries that alleviate the need for the application to call into **libpmem** +directly. Application developers that wish to access raw memory mapped +persistence directly (via **mmap**(2)) and that wish to take on the +responsibility for flushing stores to persistence will find the +functions described in this section to be the most commonly used. + +The **pmem_is_pmem**() function detects if the entire range +\[*addr*, *addr*+*len*) consists of persistent memory. Calling this function +with a memory range that originates from a source different than +**pmem_map_file()** is undefined. The implementation of **pmem_is_pmem**() +requires a non-trivial amount of work to determine if the given range is +entirely persistent memory. For this reason, it is better to call +**pmem_is_pmem**() once when a range of memory is first encountered, +save the result, and use the saved result to determine whether +**pmem_persist**(3) or **msync**(2) is appropriate for flushing changes to +persistence. Calling **pmem_is_pmem**() each time changes are flushed to +persistence will not perform well. + +The **pmem_map_file**() function creates a new read/write mapping for a +file. If **PMEM_FILE_CREATE** is not specified in *flags*, the entire existing +file *path* is mapped, *len* must be zero, and *mode* is ignored. Otherwise, +*path* is opened or created as specified by *flags* and *mode*, and *len* +must be non-zero. **pmem_map_file**() maps the file using **mmap**(2), but it +also takes extra steps to make large page mappings more likely. + +On success, **pmem_map_file**() returns a pointer to the mapped area. If +*mapped_lenp* is not NULL, the length of the mapping is stored into +\**mapped_lenp*. If *is_pmemp* is not NULL, a flag indicating whether the +mapped file is actual pmem, or if **msync**() must be used to flush writes +for the mapped range, is stored into \**is_pmemp*. + +The *flags* argument is 0 or the bitwise OR of one or more of the +following file creation flags: + ++ **PMEM_FILE_CREATE** - Create the file named *path* if it does not exist. + *len* must be non-zero and specifies the size of the file to be created. + If the file already exists, it will be extended or truncated to *len.* + The new or existing file is then fully allocated to size *len* using + **posix_fallocate**(3). + *mode* specifies the mode to use in case a new file is created (see + **creat**(2)). + +The remaining flags modify the behavior of **pmem_map_file**() when +**PMEM_FILE_CREATE** is specified. + ++ **PMEM_FILE_EXCL** - If specified in conjunction with **PMEM_FILE_CREATE**, + and *path* already exists, then **pmem_map_file**() will fail with **EEXIST**. + Otherwise, has the same meaning as **O_EXCL** on **open**(2), which is + generally undefined. + ++ **PMEM_FILE_SPARSE** - When specified in conjunction with + **PMEM_FILE_CREATE**, create a sparse (holey) file using **ftruncate**(2) + rather than allocating it using **posix_fallocate**(3). Otherwise ignored. + ++ **PMEM_FILE_TMPFILE** - Create a mapping for an unnamed temporary file. + Must be specified with **PMEM_FILE_CREATE**. *len* must be non-zero, + *mode* is ignored (the temporary file is always created with mode 0600), + and *path* must specify an existing directory name. If the underlying file + system supports **O_TMPFILE**, the unnamed temporary file is created in + the filesystem containing the directory *path*; if **PMEM_FILE_EXCL** + is also specified, the temporary file may not subsequently be linked into + the filesystem (see **open**(2)). + Otherwise, the file is created in *path* and immediately unlinked. + +The *path* can point to a Device DAX. In this case only the +**PMEM_FILE_CREATE** and **PMEM_FILE_SPARSE** flags are valid, but they are +both ignored. For Device DAX mappings, *len* must be equal to +either 0 or the exact size of the device. + +To delete mappings created with **pmem_map_file**(), use **pmem_unmap**(). + +The **pmem_unmap**() function deletes all the mappings for the +specified address range, and causes further references to addresses +within the range to generate invalid memory references. It will use the +address specified by the parameter *addr*, where *addr* must be a +previously mapped region. **pmem_unmap**() will delete the mappings +using **munmap**(2). + +# RETURN VALUE # + +The **pmem_is_pmem**() function returns true only if the entire range +\[*addr*, *addr*+*len*) consists of persistent memory. A true return +from **pmem_is_pmem**() means it is safe to use **pmem_persist**(3) +and the related functions to make changes durable for that memory +range. See also **CAVEATS**. + +On success, **pmem_map_file**() returns a pointer to the memory-mapped region +and sets \**mapped_lenp* and \**is_pmemp* if they are not NULL. +On error, it returns NULL, sets *errno* appropriately, and does not modify +\**mapped_lenp* or \**is_pmemp*. + +On success, **pmem_unmap**() returns 0. On error, it returns -1 and sets +*errno* appropriately. + +# NOTES # + +**pmem_is_pmem**() returns true if the entire range was mapped directly +from Device DAX (/dev/daxX.Y) without an intervening file system, +or **MAP_SYNC** flag of **mmap(2)** is supported by the file system +on Filesystem DAX. + +# CAVEATS # + +The result of **pmem_is_pmem**() query is only valid for the mappings +created using **pmem_map_file**(). For other memory regions, in particular +those created by a direct call to **mmap**(2), **pmem_is_pmem**() always +returns false, even if the queried range is entirely persistent memory. + +Not all file systems support **posix_fallocate**(3). **pmem_map_file**() will +fail if **PMEM_FILE_CREATE** is specified without **PMEM_FILE_SPARSE** and +the underlying file system does not support **posix_fallocate**(3). + +# SEE ALSO # + +**creat**(2), **ftruncate**(2), **mmap**(2), **msync**(2), **munmap**(2), +**open**(2), **pmem_persist**(3), +**posix_fallocate**(3), **libpmem**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem/pmem_memmove_persist.3.md b/content/pmdk/manpages/linux/v2.0/libpmem/pmem_memmove_persist.3.md new file mode 100644 index 0000000000..179945e100 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem/pmem_memmove_persist.3.md @@ -0,0 +1,149 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem_memmove_persist.3.html"] +title: "libpmem | PMDK" +header: "pmem API version 1.1" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2020, Intel Corporation) + +[comment]: <> (pmem_memmove_persist.3 -- man page for functions that provide optimized copying to persistent memory + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem_memmove**(), **pmem_memcpy**(), **pmem_memset**(), +**pmem_memmove_persist**(), **pmem_memcpy_persist**(), **pmem_memset_persist**(), +**pmem_memmove_nodrain**(), **pmem_memcpy_nodrain**(), **pmem_memset_nodrain**() +- functions that provide optimized copying to persistent memory + +# SYNOPSIS # + +```c +#include + +void *pmem_memmove(void *pmemdest, const void *src, size_t len, unsigned flags); +void *pmem_memcpy(void *pmemdest, const void *src, size_t len, unsigned flags); +void *pmem_memset(void *pmemdest, int c, size_t len, unsigned flags); +void *pmem_memmove_persist(void *pmemdest, const void *src, size_t len); +void *pmem_memcpy_persist(void *pmemdest, const void *src, size_t len); +void *pmem_memset_persist(void *pmemdest, int c, size_t len); +void *pmem_memmove_nodrain(void *pmemdest, const void *src, size_t len); +void *pmem_memcpy_nodrain(void *pmemdest, const void *src, size_t len); +void *pmem_memset_nodrain(void *pmemdest, int c, size_t len); +``` + +# DESCRIPTION # + +**pmem_memmove**(), **pmem_memcpy**() and **pmem_memset**() functions provide +the same memory copying as their namesakes **memmove**(3), **memcpy**(3) and +**memset**(3), and ensure that the result has been flushed to persistence before +returning (unless **PMEM_F_MEM_NOFLUSH** flag was used). + +For example, the following code is functionally equivalent to **pmem_memmove**() (with flags equal to 0): + +```c + memmove(dest, src, len); + pmem_persist(dest, len); +``` + +Calling **pmem_memmove**() may out-perform the above code, because +**libpmem**(7) implementation may take advantage of the fact that *pmemdest* +is persistent memory and use instructions such as *non-temporal* stores to +avoid the need to flush processor caches. + +>WARNING: +Using these functions where **pmem_is_pmem**(3) returns false +may not do anything useful. Use libc functions in that case. + +Unlike libc implementation, **libpmem** functions guarantee that if destination +buffer address and length are 8 byte aligned then all stores will be performed +using at least 8 byte store instructions. This means that a series of 8 byte +stores followed by **pmem_persist**(3) can be safely replaced by a single call +to one of the above functions. + +The *flags* argument of all of the above functions has the same meaning. +It can be 0 or a bitwise OR of one or more of the following flags: + ++ **PMEM_F_MEM_NODRAIN** - modifies the behavior to skip the final + **pmem_drain**() step. This allows applications to optimize cases where + several ranges are being copied to persistent memory, followed by a single + call to **pmem_drain**(). The following example illustrates how this flag + might be used to avoid multiple calls to **pmem_drain**() when copying several + ranges of memory to pmem: + +```c +/* ... write several ranges to pmem ... */ +pmem_memcpy(pmemdest1, src1, len1, PMEM_F_MEM_NODRAIN); +pmem_memcpy(pmemdest2, src2, len2, PMEM_F_MEM_NODRAIN); + +/* ... */ + +/* wait for any pmem stores to drain from HW buffers */ +pmem_drain(); +``` + ++ **PMEM_F_MEM_NOFLUSH** - Don't flush anything. This implies **PMEM_F_MEM_NODRAIN**. + Using this flag only makes sense when it's followed by any function that + flushes data. + +The remaining flags say *how* the operation should be done, and are merely hints. + ++ **PMEM_F_MEM_NONTEMPORAL** - Use non-temporal instructions. + This flag is mutually exclusive with **PMEM_F_MEM_TEMPORAL**. + On x86\_64 this flag is mutually exclusive with **PMEM_F_MEM_NOFLUSH**. + ++ **PMEM_F_MEM_TEMPORAL** - Use temporal instructions. + This flag is mutually exclusive with **PMEM_F_MEM_NONTEMPORAL**. + ++ **PMEM_F_MEM_WC** - Use write combining mode. + This flag is mutually exclusive with **PMEM_F_MEM_WB**. + On x86\_64 this flag is mutually exclusive with **PMEM_F_MEM_NOFLUSH**. + ++ **PMEM_F_MEM_WB** - Use write back mode. + This flag is mutually exclusive with **PMEM_F_MEM_WC**. + On x86\_64 this is an alias for **PMEM_F_MEM_TEMPORAL**. + +Using an invalid combination of flags has undefined behavior. + +Without any of the above flags **libpmem** will try to guess the best strategy +based on size. See **PMEM_MOVNT_THRESHOLD** description in **libpmem**(7) for +details. + +**pmem_memmove_persist**() is an alias for **pmem_memmove**() with flags equal to 0. + +**pmem_memcpy_persist**() is an alias for **pmem_memcpy**() with flags equal to 0. + +**pmem_memset_persist**() is an alias for **pmem_memset**() with flags equal to 0. + +**pmem_memmove_nodrain**() is an alias for **pmem_memmove**() with flags equal to **PMEM_F_MEM_NODRAIN**. + +**pmem_memcpy_nodrain**() is an alias for **pmem_memcpy**() with flags equal to **PMEM_F_MEM_NODRAIN**. + +**pmem_memset_nodrain**() is an alias for **pmem_memset**() with flags equal to **PMEM_F_MEM_NODRAIN**. + +# RETURN VALUE # + +All of the above functions return address of the destination buffer. + +# CAVEATS # +After calling any of the functions with **PMEM_F_MEM_NODRAIN** flag you +should not expect memory to be visible to other threads before calling +**pmem_drain**(3) or any of the *\_persist* functions. This is because on +x86\_64 those functions may use non-temporal store instructions, which are +weakly ordered. See "Intel 64 and IA-32 Architectures Software Developer's Manual", +Volume 1, "Caching of Temporal vs. Non-Temporal Data" section for details. + +# SEE ALSO # + +**memcpy**(3), **memmove**(3), **memset**(3), +**libpmem**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2.7.md b/content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2.7.md new file mode 100644 index 0000000000..8b705250c9 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2.7.md @@ -0,0 +1,301 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["libpmem2.7.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019-2023, Intel Corporation) + +[comment]: <> (libpmem2.7 -- man page for libpmem2) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[GRANULARITY](#granularity)
+[CAVEATS](#caveats)
+[ENVIRONMENT](#environment)
+[DEBUGGING](#debugging)
+[EXAMPLE](#example)
+[ACKNOWLEDGEMENTS](#acknowledgements)
+[SEE ALSO](#see-also) + +# NAME # + +**libpmem2** - persistent memory support library + +# SYNOPSIS # + +```c +#include +cc ... -lpmem2 +``` + +# DESCRIPTION # + +**libpmem2** provides low-level *persistent memory* (pmem) support for +applications using direct access storage (DAX), which is storage that +supports load/store access without paging blocks from a block storage +device. Some types of *non-volatile memory DIMMs* (NVDIMMs) provide this +type of byte addressable access to storage. A *persistent memory aware +file system* is typically used to expose the direct access to +applications. Memory mapping a file from this type of file system +results in the load/store, non-paged access to pmem. + +This library is for applications that use persistent memory directly, +without the help of any library-supplied transactions or memory +allocation. A higher-level library that *currently* build on **libpmem** +(previous variation of libpmem2) is available and recommended +for most applications, see: + ++ **libpmemobj**(7), a general use persistent memory API, providing memory + allocation and transactional operations on variable-sized objects. + +The **libpmem2** library provides a comprehensive set of functions for +robust use of Persistent Memory. It relies on three core concepts: +*struct pmem2_src source*, *struct pmem2_config config* and *struct pmem2_map map*: + +* *source* - an object describing the data source for mapping. +The data source can be a file descriptor or an anonymous mapping. +APIs dedicated for creating *source* are: **pmem2_source_from_fd**(3), +**pmem2_source_from_anon**(3). + +* *config* - an object containing parameters that are used to create a mapping from a *source*. +The configuration structure must always be provided to create a mapping, +but the only required parameter to set in the *config* is *granularity*. +The granularity should by set using dedicated **libpmem2** function +**pmem2_config_set_required_store_granularity**(3) which defines a maximum permitted +granularity requested by the user. For more information about the granularity concept +read **GRANULARITY** section below. + +In addition to the granularity setting, libpmem2 provides multiple optional +functions to configure target mapping, e.g., **pmem2_config_set_length**(3) +to set length which will be used for mapping, or **pmem2_config_set_offset**(3) +which will be used to map the contents from the specified location of the source, +**pmem2_config_set_sharing**(3) which defines the behavior and visibility of writes +to the mapping's pages. + +* *map* - an object created by **pmem2_map_new**(3) using *source* and +*config* as an input parameters. The map structure can be then used to +directly operate on the created mapping through the use of its associated +set of functions: **pmem2_map_get_address**(3), **pmem2_map_get_size**(3), +**pmem2_map_get_store_granularity**(3) - for getting address, +size and effective mapping granularity. + +In addition to the basic functionality of managing the virtual address mapping, +**libpmem2** also provides optimized functions for modifying the mapped data. +This includes data flushing as well as memory copying. + +To get proper function for data flushing use: **pmem2_get_flush_fn**(3), +**pmem2_get_persist_fn**(3) or **pmem2_get_drain_fn**(3). +To get proper function for copying to persistent memory, use *map* getters: +**pmem2_get_memcpy_fn**(3), **pmem2_get_memset_fn**(3), **pmem2_get_memmove_fn**(3). + +The **libpmem2** API also provides support for the badblock and unsafe shutdown +state handling. + +To read or clear badblocks, the following functions are provided: +**pmem2_badblock_context_new**(3), **pmem2_badblock_context_delete**(3), +**pmem2_badblock_next**(3) and **pmem2_badblock_clear**(3). + +To handle unsafe shutdown in the application, the following functions are provided: +**pmem2_source_device_id**(3), **pmem2_source_device_usc**(3). +More detailed information about unsafe shutdown detection and unsafe shutdown count +can be found in the **libpmem2_unsafe_shutdown**(7) man page. + +# GRANULARITY # + +The **libpmem2** library introduces the concept of granularity through which you +may easily distinguish between different levels of storage performance +capabilities available to the application as related to *power-fail protected domain*. +The way data reaches this protected domain differs based on the platform +and storage device capabilities. + +Traditional block storage devices (SSD, HDD) must use system API calls such +as `msync()`, `fsync()` to write data reliably. Invoking these functions +flushes the data to the medium with page granularity. In the **libpmem2** library, +this type of flushing behavior is called **PMEM2_GRANULARITY_PAGE**. + +In systems with persistent memory support, a *power-fail protected domain* may +cover different sets of resources: either the memory controller or the memory +controller and CPU caches. For this reason, **libpmem2** distinguishes two types +of granularity for persistent memory: +**PMEM2_GRANULARITY_CACHE_LINE** and **PMEM2_GRANULARITY_BYTE**. + +If the *power-fail protected domain* covers only the memory controller, the +CPU appropriate cache lines must be flushed for the data to be considered +persistent. This granularity type is called **PMEM2_GRANULARITY_CACHE_LINE**. +Depending on the architecture, there are +different types of machine instructions for flushing *cache lines* +(e.g., *CLWB*, *CLFLUSHOPT*, *CLFLUSH* for Intel x86_64 architecture). Usually, +to ensure the ordering of stores, such instructions must be followed +by a barrier (e.g., *SFENCE*). + +The third type of granularity **PMEM2_GRANULARITY_BYTE** applies to platforms +where *power-fail protected domain* covers both the memory controller and +CPU caches. In such cases, cache flush instructions are no longer needed, and +the platform itself guarantees the persistence of data. But barriers might +still be required for ordering. + +The library declares these granularity level in *pmem2_granularity* enum, which +the application must set in *pmem2_config* to the appropriate level for +a mapping to succeed. The software should set this config parameter to a value +that most accurately represents the target hardware characteristics and +the storage patterns of the application. For example, a database storage engine +that operates on large logical pages that reside either on SSDs or PMEM should +set this value to **PMEM2_GRANULARITY_PAGE**. +The library will create mappings where the new map granularity is lower or +equal to the requested one. For example, a mapping with **PMEM2_GRANULARITY_CACHE_LINE** +can be created for the required granularity **PMEM2_GRANULARITY_PAGE**, but not +vice versa. + +# CAVEATS # + +**libpmem2** relies on the library destructor being called from the main thread. For this reason, all functions that might trigger destruction (e.g. dlclose(3)) should be called in the main thread. Otherwise some of the resources associated with that thread might not be cleaned up properly. + +# ENVIRONMENT # + +**libpmem2** can change its default behavior based on the following +environment variables. These are primarily intended for testing and are +generally not required. + ++ **PMEM2_FORCE_GRANULARITY**=*val* + +Setting this environment variable to *val* forces **libpmem2** to +use persist method specific for forced granularity and skip +granularity autodetecting mechanism. The concept of the granularity is +described in *GRANULARITY* section above. +This variable is intended for use during library testing. + +The *val* argument accepts following text values: + ++ **BYTE** - force byte granularity. ++ **CACHE_LINE** - force cache line granularity. ++ **PAGE** - force page granularity. + +Granularity values listed above are case-insensitive. + +>NOTE: +The value of **PMEM2_FORCE_GRANULARITY** is not queried (and cached) +at library initialization time, but read during each **pmem2_map_new**(3) call. + +This means that **PMEM2_FORCE_GRANULARITY** may still be set or modified +by the program until the first attempt to map a file. + ++ **PMEM_NO_CLWB**=1 + +Setting this environment variable to 1 forces **libpmem2** to never issue +the **CLWB** instruction on Intel hardware, falling back to other cache +flush instructions on that hardware instead (**CLFLUSHOPT** or **CLFLUSH**). +Without this setting, **libpmem2** will always use the **CLWB** instruction +for flushing processor caches on platforms that support this instruction. +This variable is intended for use during library testing, but may be required +for some rare cases when using **CLWB** has a negative impact on performance. + ++ **PMEM_NO_CLFLUSHOPT**=1 + +Setting this environment variable to 1 forces **libpmem2** to never issue +the **CLFLUSHOPT** instruction on Intel hardware, falling back to the +**CLFLUSH** instructions instead. Without this environment variable, +**libpmem2** will always use the **CLFLUSHOPT** instruction for flushing +processor caches on platforms that support the instruction, but where +**CLWB** is not available. This variable is intended for use during +library testing. + ++ **PMEM_NO_MOVNT**=1 + +Setting this environment variable to 1 forces **libpmem2** to never use +the *non-temporal* move instructions on Intel hardware. Without this +environment variable, **libpmem2** will use the non-temporal instructions +for copying larger ranges to persistent memory on platforms that support +these instructions. This variable is intended for use during library +testing. + ++ **PMEM_MOVNT_THRESHOLD**=*val* + +This environment variable allows overriding the minimum length of +the *pmem2_memmove_fn* operations, for which **libpmem2** uses +*non-temporal* move instructions. Setting this environment variable to 0 +forces **libpmem2** to always use the *non-temporal* move instructions if +available. It has no effect if **PMEM_NO_MOVNT** is set to 1. +This variable is intended for use during library testing. + +# DEBUGGING # + +Two versions of **libpmem2** are typically available on a development +system. The normal version, accessed when a program is linked using the +**-lpmem2** option, is optimized for performance. That version skips checks +that impact performance and never logs any trace information or performs any +run-time assertions. + +A second version of **libpmem2**, accessed when a program uses the libraries +under **/usr/lib/pmdk_debug**, contains run-time assertions and trace points. +The typical way to access the debug version is to set the environment variable +**LD_LIBRARY_PATH** to **/usr/lib/pmdk_debug** or **/usr/lib64/pmdk_debug**, +as appropriate. Debugging output is controlled using the following environment +variables. These variables have no effect on the non-debug version of the library. + ++ **PMEM2_LOG_LEVEL** + +The value of **PMEM2_LOG_LEVEL** enables trace points in the debug version +of the library, as follows: + ++ **0** - This is the default level when **PMEM2_LOG_LEVEL** is not set. +No log messages are emitted at this level. + ++ **1** - Additional details on any errors detected are logged, in addition +to returning the *errno*-based errors as usual. The same information +may be retrieved using **pmem2_errormsg**(). + ++ **2** - A trace of basic operations is logged. + ++ **3** - Enables a very verbose amount of function call tracing in the +library. + ++ **4** - Enables voluminous and fairly obscure tracing +information that is likely only useful to the **libpmem2** developers. + +Unless **PMEM2_LOG_FILE** is set, debugging output is written to *stderr*. + ++ **PMEM2_LOG_FILE** + +Specifies the name of a file where +all logging information should be written. 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 **PMEM2_LOG_FILE** is not set, output is +written to *stderr*. + +# EXAMPLE # + +See for examples using the **libpmem2** API. + +The basic example uses **libpmem2** to flush changes made to raw, +memory-mapped persistent memory. + +>WARNING: +There is nothing transactional about the *persist* from **pmem2_get_persist_fn**(3) +call in this example. Interrupting the program may result in a partial write to pmem. +Use a transactional library such as **libpmemobj**(7) to avoid torn updates. + +# ACKNOWLEDGEMENTS # + +**libpmem2** builds on the persistent memory programming model recommended +by the SNIA NVM Programming Technical Work Group: + + +# SEE ALSO # + +**FlushFileBuffers**(), **fsync**(2), **msync**(2), +**pmem2_config_set_length**(3), **pmem2_config_set_offset**(3), +**pmem2_config_set_required_store_granularity**(3), +**pmem2_config_set_sharing**(3),**pmem2_get_drain_fn**(3), +**pmem2_get_flush_fn**(3), **pmem2_get_memcpy_fn**(3), +**pmem2_get_memmove_fn**(3), **pmem2_get_memset_fn**(3), +**pmem2_get_persist_fn**(3),**pmem2_map_get_store_granularity**(3), +**pmem2_map_new**(3), **pmem2_source_from_anon**(3), +**pmem2_source_from_fd**(3), **libpmem2_unsafe_shutdown**(7), +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2_unsafe_shutdown.7.md b/content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2_unsafe_shutdown.7.md new file mode 100644 index 0000000000..cfd7d42c37 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/libpmem2_unsafe_shutdown.7.md @@ -0,0 +1,85 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["libpmem2_unsafe_shutdown.7.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2021, Intel Corporation) + +[comment]: <> (libpmem2_unsafe_shutdown.7 -- man page for libpmem2 unsafe shutdown) + +[NAME](#name)
+[DESCRIPTION](#description)
+[UNSAFE SHUTDOWN DETECTION](#unsafe-shutdown-detection)
+[SEE ALSO](#see-also) + +# NAME # + +**libpmem2_unsafe_shutdown** - libpmem2 unsafe shutdown + +# DESCRIPTION # + +In systems with the persistent memory support, *a power-fail protected domain* +covers a set of resources from which the platform will flush data to +*the persistent medium* in case of *a power-failure*. Data stored on +*the persistent medium* is preserved across power cycles. + +The hardware guarantees the feature to flush all data stored in +*the power-fail protected domain* to *the persistent medium*. However, nothing +is infallible, and Persistent Memory hardware can expose a monotonically +increasing *unsafe shutdown counter* (**USC**) that is incremented every time +a failure of the mechanism above is detected. This allows software to discover +situations where a running application was interrupted by a power failure that +led to an unsafe shutdown. Undiscovered unsafe shutdowns might cause silent data +corruption. + +>Note: *The unsafe shutdown* may corrupt data stored on a device, in a file, +in a set of files, and a mapping spanning only a part of a file. +For the sake of simplicity, all of the above cases will be called *file* below. + +# UNSAFE SHUTDOWN DETECTION # + +Software can detect an unsafe shutdown by watching for the change between +unsafe shutdown count value across application startups. Any changes can be +indicative of unsafe shutdown occurrence. + +Applications can implement a detection mechanism by storing the **USC** retrieved +from **pmem2_source_device_usc**(3) in Persistent Memory. Then, on subsequent +startups, the stored value must be compared with a newly retrieved one. + +However, this detection method can result in false-positives. Moving the file to +different Persistent Memory devices with possibly different **USC** values would +lead to false unsafe shutdown detection. + +Additionally, relying on **USC** value alone could result in the detection of +unsafe shutdown events that occur when such a shutdown has no chance of impacting +the data used by the application, e.g., when nothing is actively using the file. + +Applications can avoid false-positives associated with moving the file by storing +device identification, obtained through **pmem2_source_device_id**(3), alongside +the **USC**. This enables the software to check if the underlying device has +changed, and reinitialize the stored **USC** in such cases. + +The second behavior, detection of possibly irrelevant unsafe shutdown events, +if undesirable, can be prevented by storing a flag indicating whether the file +is in use, alongside all the rest of the relevant information. + +The application should use **pmem2_deep_flush**(3) when storing any data related +to unsafe shutdown detection for higher reliability. This helps ensure that the +detection mechanism is not reliant on the correct functioning of the same hardware +features it is designed to safeguard. + +General-purpose software should not assume the presence of **USC** on the platform, +and should instead appropriately handle any *PMEM2_E_NOSUPP* it encounters. +Doing otherwise might cause the software to be unnecessarily restrictive about +the hardware it supports and would prevent, e.g., testing on emulated PMEM. + +# SEE ALSO # + +**pmem2_deep_flush**(3), **pmem2_persist_fn**(3), **pmem2_source_device_id**(3), +**pmem2_source_device_usc**(3) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_clear.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_clear.3.md new file mode 100644 index 0000000000..1c98355231 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_clear.3.md @@ -0,0 +1,77 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_badblock_clear.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_badblock_clear.3 -- man page for pmem2_badblock_clear) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_badblock_clear**() - clear the given bad block + +# SYNOPSIS # + +```c +#include + +struct pmem2_badblock; +struct pmem2_badblock_context; + +int pmem2_badblock_clear( + struct pmem2_badblock_context *bbctx, + struct pmem2_badblock *bb); +``` + +# DESCRIPTION # + +The **pmem2_badblock_clear**() function clears the given *\*bb* bad block. + +It means that the **pmem2_badblock_clear**() function unmaps bad blocks +and maps new, healthy, blocks in place of the bad ones. +The new blocks are zeroed. The content of the bad blocks is lost. + +# RETURN VALUE # + +The **pmem2_badblock_clear**() function clears the given *\*bb* bad block +and returns 0 on success or a negative error code on failure. + +# ERRORS # + +**pmem2_badblock_clear**() can fail with the following errors: + +* **PMEM2_E_OFFSET_OUT_OF_RANGE** - bad block's offset is greater than INT64_MAX + +* **PMEM2_E_LENGTH_OUT_OF_RANGE** - bad block's length is greater than INT64_MAX + +* **PMEM2_E_NOSUPP** - when the OS does not support this functionality + +* **-errno** - set by failing **fallocate**(2), while deallocating bad blocks +or allocating new blocks + +* **-errno** - set by failing ndctl functions: **ndctl_bus_cmd_new_ars_cap**, +**ndctl_cmd_submit**, **ndctl_cmd_ars_cap_get_range** or +**ndctl_bus_cmd_new_clear_error** while trying to clear a bad block +in a DAX device + +* **-ENXIO** - **ndctl_bus_cmd_new_clear_error** did not manage to clear +all bad blocks + +# SEE ALSO # + +**pmem2_badblock_context_new**(3), **pmem2_badblock_next**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_context_new.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_context_new.3.md new file mode 100644 index 0000000000..7dd6c58374 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_context_new.3.md @@ -0,0 +1,116 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_badblock_context_new.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_badblock_context_new.3 -- man page for) +[comment]: <> (pmem2_badblock_context_new and pmem2_badblock_context_delete) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_badblock_context_new**(), **pmem2_badblock_context_delete**() - +allocate and free a context for **pmem2_badblock_next**() and +**pmem2_badblock_clear**() operations + +# SYNOPSIS # + +```c +#include + +struct pmem2_source; +struct pmem2_badblock_context; + +int pmem2_badblock_context_new( + struct pmem2_badblock_context **bbctx, + const struct pmem2_source *src); + +void pmem2_badblock_context_delete( + struct pmem2_badblock_context **bbctx); +``` + +# DESCRIPTION # + +The **pmem2_badblock_context_new**() function instantiates a new (opaque) +bad block context structure, *pmem2_badblock_context*, which is used to read +and clear bad blocks (by **pmem2_badblock_next**() and +**pmem2_badblock_clear**()). The function returns the bad block context +through the pointer in *\*bbctx*. + +New bad block context structure is initialized with values read from the source +given as the first argument (*src*). + +A bad block is an uncorrectable media error - a part of a storage media +that is either inaccessible or unwritable due to permanent physical damage. +In case of memory-mapped I/O, if a process tries to access (read or write) +the corrupted block, it will be terminated by the SIGBUS signal. + +The **pmem2_badblock_context_delete**() function frees *\*bbctx* returned by +**pmem2_badblock_context_new**() and sets *\*bbctx* to NULL. If *\*bbctx* +is NULL, no operation is performed. + +# RETURN VALUE # + +The **pmem2_badblock_context_new**() function returns 0 on success +or a negative error code on failure. + +The **pmem2_badblock_context_new**() sets *\*bbctx* to NULL on failure. + +The **pmem2_badblock_context_delete**() does not return any value. + +# ERRORS # + +The **pmem2_badblock_context_new**() can fail with the following errors: + +* **PMEM2_E_INVALID_FILE_TYPE** - *src* is not a regular file nor +a character device. + +* **PMEM2_E_DAX_REGION_NOT_FOUND** - cannot find a DAX region for +the given *src*. + +* **PMEM2_E_CANNOT_READ_BOUNDS** - cannot read offset or size of the namespace +of the given *src*. + +* **PMEM2_E_NOSUPP** - when the OS does not support this functionality + +* **-ENOMEM** - out of memory + +* **-errno** - set by failing **ndctl_new**, while trying to create +a new ndctl context. + +* **-errno** - set by failing **fstat**(2), while trying to validate +the file descriptor of *src*. + +* **-errno** - set by failing **realpath**(3), while trying to get +the canonicalized absolute sysfs pathname of DAX device given in *src*. + +* **-errno** - set by failing **open**(2), while trying to open the FSDAX device +matching with the *src*. + +* **-errno** - set by failing **read**(2), while trying to read from the FSDAX +device matching with the *src*. + +* **-errno** - set by failing **ndctl_region_get_resource**, while reading +an offset of the region of the given *src*. + +* **-errno** - set by failing **fiemap ioctl(2)**, while reading file extents +of the given *src*. + +# SEE ALSO # + +**pmem2_badblock_next**(3), **pmem2_badblock_clear**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_next.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_next.3.md new file mode 100644 index 0000000000..0f06a25baf --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_badblock_next.3.md @@ -0,0 +1,63 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_badblock_next.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_badblock_next.3 -- man page for pmem2_badblock_next) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_badblock_next**() - read the next bad block for the given bad block +context *\*bbctx*. + +# SYNOPSIS # + +```c +#include + +struct pmem2_badblock; +struct pmem2_badblock_context; + +int pmem2_badblock_next( + struct pmem2_badblock_context *bbctx, + struct pmem2_badblock *bb); +``` + +# DESCRIPTION # + +The **pmem2_badblock_next**() function reads the next bad block for the given +bad block context *\*bbctx*. + +# RETURN VALUE # + +The **pmem2_badblock_next**() function returns 0 and stores the next bad block +in *\*bb* on success or it returns a negative error code when there are no more +bad blocks for the given bad block context *\*bbctx*. + +# ERRORS # + +**pmem2_badblock_next**() can fail with the following error: + +* **PMEM2_E_NO_BAD_BLOCK_FOUND** - there are no more bad blocks for the given +bad block context *\*bbctx*, *\*bb* is undefined in this case. + +* **PMEM2_E_NOSUPP** - when the OS does not support this functionality + +# SEE ALSO # + +**pmem2_badblock_context_new**(3), **pmem2_badblock_clear**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_new.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_new.3.md new file mode 100644 index 0000000000..d5b1f1290b --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_new.3.md @@ -0,0 +1,63 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_config_new.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_config_new.3 -- man page for pmem2_config_new and pmem2_config_delete) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_config_new**(), **pmem2_config_delete**() - allocate and free a +configuration structure for a libpmem2 mapping + +# SYNOPSIS # + +```c +#include + +struct pmem2_config; +int pmem2_config_new(struct pmem2_config **cfg); +int pmem2_config_delete(struct pmem2_config **cfg); +``` + +# DESCRIPTION # + +The **pmem2_config_new**() function instantiates a new (opaque) configuration structure, *pmem2_config*, which is used to define mapping parameters for a **pmem2_map_new**() function, and returns it through the pointer in *\*cfg*. + +New configuration is always initialized with default values for most parameters, +which are specified alongside the corresponding setter function. +The application must explicitly set the granularity value for the mapping. + +The **pmem2_config_delete**() function frees *\*cfg* returned by **pmem2_config_new**() and sets *\*cfg* to NULL. +If *\*cfg* is NULL, no operation is performed. + +# RETURN VALUE # + +The **pmem2_config_new**() function returns 0 on success or a negative error code on failure. +**pmem2_config_new**() does set *\*cfg* to NULL on failure. + +The **pmem2_config_delete**() function always returns 0. + +# ERRORS # + +**pmem2_config_new**() can fail with the following error: +- **-ENOMEM** - out of memory + +# SEE ALSO # + +**errno**(3), **pmem2_map_new**(3), **pmem2_config_get_file_size**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_length.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_length.3.md new file mode 100644 index 0000000000..16e08a5187 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_length.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: ["pmem2_config_set_length.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019, Intel Corporation) + +[comment]: <> (pmem2_config_set_length.3 -- man page for libpmem2 config API) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_config_set_length**() - set length in the pmem2_config structure + +# SYNOPSIS # + +```c +#include + +struct pmem2_config; +int pmem2_config_set_length(struct pmem2_config *config, size_t length); +``` + +# DESCRIPTION # + +The **pmem2_config_set_length**() function configures the length which will be used +for mapping. *\*config* should be already initialized, please see **pmem2_config_new**(3) +for details. The *\length* must be a multiple of the alignment required for the data +source which will be used for mapping alongside the config. +To retrieve the alignment required for specific instance of *pmem2_source** use +**pmem2_source_alignment**(3). +By default, the length is equal to the size of the file that is being mapped. + +# RETURN VALUE # + +The **pmem2_config_set_length**() function always returns 0. + +# SEE ALSO # + +**libpmem2**(7), **pmem2_map_new**(3), **pmem2_source_alignment**(3), +**pmem2_config_new**(3), **sysconf**(3) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_offset.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_offset.3.md new file mode 100644 index 0000000000..c7e0ec7fe1 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_offset.3.md @@ -0,0 +1,61 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_config_set_offset.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_config_set_offset.3 -- man page for libpmem2 config API) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_config_set_offset**() - set offset in the pmem2_config structure + +# SYNOPSIS # + +```c +#include + +struct pmem2_config; +int pmem2_config_set_offset(struct pmem2_config *config, size_t offset); +``` + +# DESCRIPTION # + +The **pmem2_config_set_offset**() function configures the offset which will be used +to map the contents from the specified location of the source. *\*config* should be +already initialized, please see **pmem2_config_new**(3) for details. The *\offset* +must be a multiple of the alignment required for the config. The alignment +requirements are specific to a data source. To retrieve the alignment +required for specific instance of *pmem2_source** use **pmem2_source_alignment**(3). +By default, the offset is 0. + +# RETURN VALUE # + +The **pmem2_config_set_offset**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_config_set_offset**() can fail with the following errors: + +* **PMEM2_E_OFFSET_OUT_OF_RANGE** - argument out of range, offset is greater than +**INT64_MAX** + +# SEE ALSO # + +**libpmem2**(7), **pmem2_source_alignment**(3), **pmem2_config_new**(3), +**pmem2_map_new**(3), **sysconf**(3) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_protection.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_protection.3.md new file mode 100644 index 0000000000..e2dd0cf6c8 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_protection.3.md @@ -0,0 +1,77 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_config_set_protection.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_config_set_protection.3 -- man page for libpmem2 config API) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_config_set_protection**() - set a protection flags in pmem2_config structure. + +# SYNOPSIS # + +```c +#include + +struct pmem2_config; + +#define PMEM2_PROT_EXEC (1U << 29) +#define PMEM2_PROT_READ (1U << 30) +#define PMEM2_PROT_WRITE (1U << 31) +#define PMEM2_PROT_NONE 0 + +int pmem2_config_set_protection(struct pmem2_config *cfg, + unsigned prot); +``` + +# DESCRIPTION # + +The **pmem2_config_set_protection**() function sets the protection flags +which will be used for memory mapping. The default value +in pmem2_config structure is **PMEM2_PROT_READ | PMEM2_PROT_WRITE**. +The *\prot* argument describes the desired memory protection of the mapping. +The memory protection cannot conflict with the file opening-mode. +*\*config* should be already initialized, +please see **pmem2_config_new**(3) for details. + +It is either PROT_NONE or the bitwise OR of one or more of the following flags: + +* **PMEM2_PROT_EXEC** - Pages may be executed. + +* **PMEM2_PROT_READ** - Pages may be read. + +* **PMEM2_PROT_WRITE** - Pages may be written. + +* **PMEM2_PROT_NONE** - Pages may not be accessed. + +# RETURN VALUE # + +The **pmem2_config_set_protection**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_config_set_protection**() can fail with the following errors: + +* **PMEM2_E_INVALID_PROT_FLAG** - some or all of the provided flags are not valid. + +# SEE ALSO # + +**libpmem2**(7), **pmem2_config_new**(3), **pmem2_map_new**(3) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_required_store_granularity.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_required_store_granularity.3.md new file mode 100644 index 0000000000..a83280ba74 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_required_store_granularity.3.md @@ -0,0 +1,71 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_config_set_required_store_granularity.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_config_set_required_store_granularity.3 -- man page for pmem2_config_set_required_store_granularity + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_config_set_required_store_granularity**() - set a granularity +in pmem2_config structure. + +# SYNOPSIS # + +```c +#include + +enum pmem2_granularity { + PMEM2_GRANULARITY_BYTE, + PMEM2_GRANULARITY_CACHE_LINE, + PMEM2_GRANULARITY_PAGE, +}; +int pmem2_config_set_required_store_granularity(struct pmem2_config *cfg, + enum pmem2_granularity g); +``` + +# DESCRIPTION # + +The **pmem2_config_set_required_store_granularity**() sets a maximum permitted +granularity *g* requested by user in the *pmem2_config* structure. + +Granularity must be one of the following values: + + * **PMEM2_GRANULARITY_BYTE** + + * **PMEM2_GRANULARITY_CACHE_LINE** + + * **PMEM2_GRANULARITY_PAGE** + +A description of the granularity concept can be found in **libpmem2**(7) manpage. + +# RETURN VALUE # + +The **pmem2_config_set_required_store_granularity**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_config_set_required_store_granularity**() can fail +with the following errors: + + * **PMEM2_E_GRANULARITY_NOT_SUPPORTED** - granularity *g* is not a valid value. + +# SEE ALSO # +**pmem2_config_new**(3), **libpmem2**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_sharing.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_sharing.3.md new file mode 100644 index 0000000000..3d0590520c --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_sharing.3.md @@ -0,0 +1,65 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_config_set_sharing.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_config_set_sharing.3 -- man page for libpmem2 config API) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_config_set_sharing**() - set sharing in the pmem2_config structure + +# SYNOPSIS # + +```c +#include + +struct pmem2_config; +enum pmem2_sharing_type { + PMEM2_SHARED, + PMEM2_PRIVATE, +}; +int pmem2_config_set_sharing(struct pmem2_config *config, enum pmem2_sharing_type sharing); +``` + +# DESCRIPTION # + +The **pmem2_config_set_sharing**() function configures the behavior and visibility +of writes to the mapping's pages. The possible values are listed below: + +* **PMEM2_SHARED** - Writes are made directly to the underlying memory, making +them visible to other mappings of the same memory region. (default) + +* **PMEM2_PRIVATE** - Writes do not affect the underlying memory and are +not visible to other mappings of the same memory region. + +# RETURN VALUE # + +The **pmem2_config_set_sharing**() function returns 0 on success +or a negative error code on failure. + +# ERRORRS # + +The **pmem2_config_set_sharing**() can fail with the following errors: + +* **PMEM2_E_INVALID_SHARING_VALUE** - *sharing* value is invalid. + +# SEE ALSO # + +**libpmem2**(7), **pmem2_config_new**(3), **pmem2_map_new**(3), **sysconf**(3) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_vm_reservation.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_vm_reservation.3.md new file mode 100644 index 0000000000..57d7509e4a --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_config_set_vm_reservation.3.md @@ -0,0 +1,51 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_config_set_vm_reservation.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_config_set_vm_reservation.3 -- man page for libpmem2 config API) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_config_set_vm_reservation**() - sets the pmem2_vm_reservation structure basing on the +values in the pmem2_config structure + +# SYNOPSIS # + +```c +#include + +struct pmem2_config; +struct pmem2_vm_reservation; +int pmem2_config_set_vm_reservation(struct pmem2_config *config, + struct pmem2_vm_reservation *rsv, size_t rsv_offset); +``` + +# DESCRIPTION # + +The **pmem2_config_set_vm_reservation**() function sets the virtual memory reservation +and an offset to be used during a mapping. *rsv* should be already initialized. Please see +**pmem2_vm_reservation_new**(3) for details. *rsv_offset* marks the offset in the +reservation for the mapping. + +# RETURN VALUE # + +**pmem2_config_set_vm_reservation**() function always returns 0. + +# SEE ALSO # + +**pmem2_vm_reservation_new**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_deep_flush.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_deep_flush.3.md new file mode 100644 index 0000000000..7636c33c3f --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_deep_flush.3.md @@ -0,0 +1,68 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_deep_flush.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_deep_flush.3 -- man page for pmem2_deep_flush) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_deep_flush**() - highly reliable persistent memory synchronization + +# SYNOPSIS # + +```c +#include + +int pmem2_deep_flush(struct pmem2_map *map, void *ptr, size_t size) +``` + +# DESCRIPTION # + +The **pmem2_deep_flush**() function forces any changes in the range \[*ptr*, *ptr*+*len*) +from the *map* to be stored durably in the most reliable persistence domain +available to software. In particular, on supported platforms, this enables +the code not to rely on automatic cache or WPQ (write pending queue) flush on power failure (ADR/eADR). + +Since this operation is usually much more expensive than regular persist, it +should be used sparingly. Typically, the application should only ever use this +function as a precaution against hardware failures, e.g., in code that detects +silent data corruption caused by unsafe shutdown (see more in **libpmem2_unsafe_shutdown**(7)). + +# RETURN VALUE # + +The **pmem2_deep_flush**() function returns 0 on success +or an error code on failure. + +# ERRORS # + +The **pmem2_deep_flush**() can fail with the following errors: + +* **PMEM2_E_DEEP_FLUSH_RANGE** - the provided flush range is not a +subset of the map's address space. + +* **PMEM2_E_DAX_REGION_NOT_FOUND** - the underlying device region id cannot be +detected. + +* -**errno** set by failing **msync**(2), while trying to perform +a deep flush on a regular DAX volume. + +# SEE ALSO # + +**msync**(2), **pmem2_get_drain_fn**(3), **pmem2_get_persist_fn**(3) +**pmem2_map**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_errormsg.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_errormsg.3.md new file mode 100644 index 0000000000..59d1f6a39b --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_errormsg.3.md @@ -0,0 +1,55 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_errormsg.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019, Intel Corporation) + +[comment]: <> (pmem2_errormsg.3 -- man page for error handling in libpmem2) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_errormsg**() - returns last error message + +# SYNOPSIS # + +```c +#include + +const char *pmem2_errormsg(void); +``` + +# DESCRIPTION # + +If an error is detected during the call to a **libpmem2**(7) function, the +application may retrieve an error message describing the reason of the failure +from **pmem2_errormsg**(). The error message buffer is thread-local; +errors encountered in one thread do not affect its value in +other threads. The buffer is never cleared by any library function; its +content is significant only when the return value of the immediately preceding +call to a **libpmem2**(7) 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. + +# RETURN VALUE # + +The **pmem2_errormsg**() function returns a pointer to a static buffer +containing the last error message logged for the current thread. If *errno* +was set, the error message may include a description of the corresponding +error code as returned by **strerror**(3). + +# SEE ALSO # + +**strerror**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_drain_fn.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_drain_fn.3.md new file mode 100644 index 0000000000..040be5fb97 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_drain_fn.3.md @@ -0,0 +1,62 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_get_drain_fn.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_get_drain_fn.3 -- man page for pmem2_get_drain_fn) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_get_drain_fn**() - get a drain function + +# SYNOPSIS # + +```c +#include + +typedef void (*pmem2_drain_fn)(void); + +struct pmem2_map; + +pmem2_drain_fn pmem2_get_drain_fn(struct pmem2_map *map); +``` + +# DESCRIPTION # + +The **pmem2_get_drain_fn**() function returns a pointer to a function +responsible for efficiently draining flushes (see **pmem2_get_flush_fn**(3)) +in the range owned by *map*. Draining, in this context, means making sure +that the flushes before this operation won't be reordered after it. +While it is not strictly true, draining can be thought of as waiting for +previous flushes to complete. + +If two (or more) mappings share the same drain function, it is safe to call +this function once for all flushes belonging to those mappings. + +# RETURN VALUE # + +The **pmem2_get_drain_fn**() function never returns NULL. + +The **pmem2_get_drain_fn**() for the same *map* always returns the same function. +This means that it's safe to cache its return value. However, this function +is very cheap (because it returns a precomputed value), so caching may not +be necessary. + +# SEE ALSO # + +**pmem2_get_flush_fn**(3), **pmem2_get_persist_fn**(3), **pmem2_map_new**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_flush_fn.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_flush_fn.3.md new file mode 100644 index 0000000000..0745395a2f --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_flush_fn.3.md @@ -0,0 +1,75 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_get_flush_fn.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_get_flush_fn.3 -- man page for pmem2_get_flush_fn) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_get_flush_fn**() - get a flush function + +# SYNOPSIS # + +```c +#include + +typedef void (*pmem2_flush_fn)(const void *ptr, size_t size); + +struct pmem2_map; + +pmem2_flush_fn pmem2_get_flush_fn(struct pmem2_map *map); +``` + +# DESCRIPTION # + +The **pmem2_get_flush_fn**() function returns a pointer to a function +responsible for efficiently flushing data in the range owned by the *map*. + +Flushing data using *pmem2_flush_fn* **does not** guarantee that the data +is stored durably by the time it returns. To get this guarantee, application +should either use the persist operation (see **pmem2_get_persist_fn**(3)) +or follow *pmem2_flush_fn* by a drain operation (see **pmem2_get_drain_fn**(3)). + +There are no alignment restrictions on the range described by *ptr* and *size*, +but *pmem2_flush_fn* may expand the range as necessary to meet platform +alignment requirements. + +There is nothing atomic or transactional about *pmem2_flush_fn*. Any +unwritten stores in the given range will be written, but some stores may have +already been written by virtue of normal cache eviction/replacement policies. +Correctly written code must not depend on stores waiting until +*pmem2_flush_fn* is called to be flushed -- they can be flushed +at any time before *pmem2_flush_fn* is called. + +If two (or more) mappings share the same *pmem2_flush_fn* and they are +adjacent to each other, it is safe to call this function for a range spanning +those mappings. + +# RETURN VALUE # + +The **pmem2_get_flush_fn**() function never returns NULL. + +The **pmem2_get_flush_fn**() for the same *map* always returns the same function. +This means that it's safe to cache its return value. However, this function +is very cheap (because it returns a precomputed value), so caching may not +be necessary. + +# SEE ALSO # + +**pmem2_get_drain_fn**(3), **pmem2_get_persist_fn**(3), **pmem2_map_new**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_memmove_fn.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_memmove_fn.3.md new file mode 100644 index 0000000000..8c84ffe3e2 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_memmove_fn.3.md @@ -0,0 +1,146 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_get_memmove_fn.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_get_memmove_fn.3 -- man page for pmem2_get_memmove_fn) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_get_memmove_fn**(), **pmem2_get_memset_fn**(), +**pmem2_get_memcpy_fn**() - get a function that provides + optimized copying to persistent memory + +# SYNOPSIS # + +```c +#include + +typedef void *(*pmem2_memmove_fn)(void *pmemdest, const void *src, size_t len, + unsigned flags); +typedef void *(*pmem2_memcpy_fn)(void *pmemdest, const void *src, size_t len, + unsigned flags); +typedef void *(*pmem2_memset_fn)(void *pmemdest, int c, size_t len, + unsigned flags); + +struct pmem2_map; + +pmem2_memmove_fn pmem2_get_memmove_fn(struct pmem2_map *map); +pmem2_memset_fn pmem2_get_memset_fn(struct pmem2_map *map); +pmem2_memcpy_fn pmem2_get_memcpy_fn(struct pmem2_map *map); +``` + +# DESCRIPTION # +The **pmem2_get_memmove_fn**(), **pmem2_get_memset_fn**(), +**pmem2_get_memcpy_fn**() functions return a pointer to a function +responsible for efficient storing and flushing of data for mapping *map*. + +**pmem2_memmove_fn**(), **pmem2_memset_fn**() and **pmem2_memcpy_fn**() +functions provide the same memory copying functionalities as their namesakes +**memmove**(3), **memcpy**(3) and **memset**(3), and ensure that the result has +been flushed to persistence before returning (unless **PMEM2_F_MEM_NOFLUSH** flag was used). + +For example, the following code: + +```c + memmove(dest, src, len); + pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map); + persist_fn(dest, len); +``` +is functionally equivalent to: + +```c + pmem2_memmove_fn memmove_fn = pmem2_get_memmove_fn(map); + memmove_fn(dest, src, len, 0); +``` + +Unlike libc implementation, **libpmem2** functions guarantee that if destination +buffer address and length are 8 byte aligned then all stores will be performed +using at least 8 byte store instructions. This means that a series of 8 byte +stores followed by *persist_fn* can be safely replaced by a single *memmove_fn* call. + +The *flags* argument of all of the above functions has the same meaning. +It can be 0 or a bitwise OR of one or more of the following flags: + ++ **PMEM2_F_MEM_NODRAIN** - modifies the behavior to skip the final + *pmem2_drain_fn* step. This allows applications to optimize cases where + several ranges are being copied to persistent memory, followed by a single + call to *pmem2_drain_fn*. The following example illustrates how this flag + might be used to avoid multiple calls to *pmem2_drain_fn* when copying several + ranges of memory to pmem: + +```c +pmem2_memcpy_fn memcpy_fn = pmem2_get_memcpy_fn(map); +pmem2_drain_fn drain_fn = pmem2_get_drain_fn(map); + +/* ... write several ranges to pmem ... */ +memcpy_fn(pmemdest1, src1, len1, PMEM2_F_MEM_NODRAIN); +memcpy_fn(pmemdest2, src2, len2, PMEM2_F_MEM_NODRAIN); + +/* ... */ + +/* wait for any pmem stores to drain from HW buffers */ +drain_fn(); +``` + ++ **PMEM2_F_MEM_NOFLUSH** - Don't flush anything. This implies **PMEM2_F_MEM_NODRAIN**. + Using this flag only makes sense when it's followed by any function that + flushes data. + +The remaining flags say *how* the operation should be done, and are merely hints. + ++ **PMEM2_F_MEM_NONTEMPORAL** - Use non-temporal instructions. + This flag is mutually exclusive with **PMEM2_F_MEM_TEMPORAL**. + On x86\_64 this flag is mutually exclusive with **PMEM2_F_MEM_NOFLUSH**. + ++ **PMEM2_F_MEM_TEMPORAL** - Use temporal instructions. + This flag is mutually exclusive with **PMEM2_F_MEM_NONTEMPORAL**. + ++ **PMEM2_F_MEM_WC** - Use write combining mode. + This flag is mutually exclusive with **PMEM2_F_MEM_WB**. + On x86\_64 this flag is mutually exclusive with **PMEM2_F_MEM_NOFLUSH**. + ++ **PMEM2_F_MEM_WB** - Use write back mode. + This flag is mutually exclusive with **PMEM2_F_MEM_WC**. + On x86\_64 this is an alias for **PMEM2_F_MEM_TEMPORAL**. + +Using an invalid combination of flags has undefined behavior. + +Without any of the above flags **libpmem2** will try to guess the best strategy +based on the data size. See **PMEM_MOVNT_THRESHOLD** description in **libpmem2**(7) for +details. + +# RETURN VALUE # + +The **pmem2_get_memmove_fn**(), **pmem2_get_memset_fn**(), +**pmem2_get_memcpy_fn**() functions never return NULL. + +They return the same function for the same mapping. + +This means that it's safe to cache their return values. However, these functions +are very cheap (because their return values are precomputed), so caching may not +be necessary. + +If two (or more) mappings share the same *pmem2_memmove_fn*, *pmem2_memset_fn*, +*pmem2_memcpy_fn* and they are adjacent to each other, it is safe to call these +functions for a range spanning those mappings. + +# SEE ALSO # + +**memcpy**(3), **memmove**(3), **memset**(3), **pmem2_get_drain_fn**(3), +**pmem2_get_memcpy_fn**(3), **pmem2_get_memset_fn**(3), **pmem2_map_new**(3), +**pmem2_get_persist_fn**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_persist_fn.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_persist_fn.3.md new file mode 100644 index 0000000000..635ca09e1e --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_get_persist_fn.3.md @@ -0,0 +1,100 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_get_persist_fn.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_get_persist_fn.3 -- man page for pmem2_get_persist_fn) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_get_persist_fn**() - get a persist function + +# SYNOPSIS # + +```c +#include + +typedef void (*pmem2_persist_fn)(const void *ptr, size_t size); + +struct pmem2_map; + +pmem2_persist_fn pmem2_get_persist_fn(struct pmem2_map *map); +``` + +# DESCRIPTION # + +The **pmem2_get_persist_fn**() function returns a pointer to a function +responsible for efficiently persisting data in the range owned by the *map*. + +Persisting data using *pmem2_persist_fn* guarantees that the data is stored +durably by the time it returns. + +There are no alignment restrictions on the range described by *ptr* and *size*, +but *pmem2_persist_fn* may expand the range as necessary to meet platform +alignment requirements. + +There is nothing atomic or transactional about *pmem2_persist_fn*. Any +unwritten stores in the given range will be written, but some stores may have +already been written by virtue of normal cache eviction/replacement policies. +Correctly written code must not depend on stores waiting until +*pmem2_persist_fn* is called to become persistent -- they can become persistent +at any time before *pmem2_persist_fn* is called. + +If two (or more) mappings share the same *pmem2_persist_fn* and they are +adjacent to each other, it is safe to call this function for a range spanning +those mappings. + +Internally *pmem2_persist_fn* performs two operations: + +- memory flush (**pmem2_get_flush_fn**(3)), which can be reordered by +the CPU with other flushes +- drain (**pmem2_get_drain_fn**(3)), which makes sure that the flushes +before this operation won't be reordered after it + +So this code: + +```c +pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map); +persist_fn(addr, len); +``` + +is equivalent of: + +```c +pmem2_flush_fn flush_fn = pmem2_get_flush_fn(map); +pmem2_drain_fn drain_fn = pmem2_get_drain_fn(map); + +flush_fn(addr, len); +drain_fn(); +``` + +Advanced applications may want to flush multiple discontiguous regions +and perform the drain operation only once. + +# RETURN VALUE # + +The **pmem2_get_persist_fn**() function never returns NULL. + +The **pmem2_get_persist_fn**() for the same *map* always returns the same function. +This means that it's safe to cache its return value. However, this function +is very cheap (because it returns a precomputed value), so caching may not be +necessary. + +# SEE ALSO # + +**pmem2_get_drain_fn**(3), **pmem2_get_flush_fn**(3), **pmem2_map_new**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_delete.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_delete.3.md new file mode 100644 index 0000000000..ec05813100 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_delete.3.md @@ -0,0 +1,66 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_map_delete.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019-2023, Intel Corporation) + +[comment]: <> (pmem2_map_delete.3 -- man page for libpmem2 pmem2_map_delete operation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_map_delete**() - deletes a mapping + +# SYNOPSIS # + +```c +#include + +int pmem2_map_delete(struct pmem2_map **map_ptr); +``` + +# DESCRIPTION # + +The **pmem2_map_delete**() function deletes the mapping described by the +*struct pmem2_map* object. + +If **pmem2_map_delete**() succeeds in deleting the mapping, it releases the +*struct pmem2_map* object describing it and writes a NULL value to *map_ptr*. +If the function fails, the *map_ptr* variable and the map object itself are left +unmodified and appropriate error value is returned. For a list of possible +return values please see [RETURN VALUE](#return-value). + +The **pmem2_map_delete**() function will not unmap mapping provided by the user +by **pmem2_map_from_existing**() function. In such case it will only free +*struct pmem2_map* object. + +# RETURN VALUE # + +The **pmem2_map_delete**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_map_delete**() can fail with the following errors: + +* **PMEM2_E_MAPPING_NOT_FOUND** - mapping was not found (it was already +unmapped or pmem2_map state was corrupted) + +* **-EINVAL** - from the underlying **munmap**(2) function. + +# SEE ALSO # + +**pmem2_map_new(3)**, **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_from_existing.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_from_existing.3.md new file mode 100644 index 0000000000..f7d6d06a75 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_from_existing.3.md @@ -0,0 +1,64 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_map_from_existing.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2021, Intel Corporation) + +[comment]: <> (pmem2_map_from_existing.3 -- man page for libpmem2 pmem2_map_from_existing operation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_map_from_existing**() - creates a pmem2_map object from an existing mapping + +# SYNOPSIS # + +```c +#include + +int pmem2_map_from_existing(struct pmem2_map **map, const struct pmem2_source *src, + void *addr, size_t len, enum pmem2_granularity gran); + +``` + +# DESCRIPTION # + +The **pmem2_map_from_existing**() returns a new *struct pmem2_map** for mapping +provided by the user. This function allows usage of **libpmem2**(7) API without **pmem2_map_new**(3) for mapping file. +Mapping is defined by *addr* and *len*. You have to specify underlying file as a *src*, and define granularity of this mapping. +See **pmem2_config_set_required_store_granularity**(3) and **libpmem2**(7) for more details. + +For the *pmem2_map* object created by the **pmem2_map_from_existing**(3) function, the **pmem2_map_delete**(3) will only destroy the object, +but it won't unmap the mapping this object describes. + +# RETURN VALUE # + +The **pmem2_map_from_existing**() function returns 0 when it succeeds +or a negative error code on failure. + +# ERRORS # + +The **pmem2_map_from_existing**() can fail with the following errors: + +**PMEM2_E_MAPPING_EXISTS** - when contiguous region (*addr*, *addr* + *len*) +is already registered by *libpmem2* + +It can also return **-ENOMEM** from the underlying **malloc**(2) function. + +# SEE ALSO # + +**malloc(2)**, **pmem2_map_delete**(3), **pmem2_map_new**(3), +**pmem2_source_from_fd**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_address.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_address.3.md new file mode 100644 index 0000000000..cb537b015f --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_address.3.md @@ -0,0 +1,46 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_map_get_address.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019, Intel Corporation) + +[comment]: <> (pmem2_map_get_address.3 -- man page for libpmem2 mapping operations) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_map_get_address**() - reads mapping address + +# SYNOPSIS # + +```c +#include + +void *pmem2_map_get_address(struct pmem2_map *map); +``` + +# DESCRIPTION # + +The **pmem2_map_get_address**() function reads address of the created mapping. +The *map* parameter points to the structure describing mapping created using +the **pmem2_map_new**(3) function. + +# RETURN VALUE # + +The **pmem2_map_get_address**() function returns a pointer to the mapped area. + +# SEE ALSO # + +**pmem2_map_new**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_size.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_size.3.md new file mode 100644 index 0000000000..ebea64b6ae --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_size.3.md @@ -0,0 +1,46 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_map_get_size.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019, Intel Corporation) + +[comment]: <> (pmem2_map_get_size.3 -- man page for libpmem2 mapping operations) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_map_get_size**() - reads mapping size + +# SYNOPSIS # + +```c +#include + +size_t pmem2_map_get_size(struct pmem2_map *map); +``` + +# DESCRIPTION # + +The **pmem2_map_get_size**() function reads size of the created mapping. +The *map* parameter points to the structure describing mapping created using +the **pmem2_map_new**(3) function. + +# RETURN VALUE # + +The **pmem2_map_get_size**() function returns a size of the mapped area. + +# SEE ALSO # + +**pmem2_map_new**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_store_granularity.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_store_granularity.3.md new file mode 100644 index 0000000000..20f906b2c2 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_get_store_granularity.3.md @@ -0,0 +1,54 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_map_get_store_granularity.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_map_get_store_granularity.3 -- man page for libpmem2 mapping) +[comment]: <> (operations) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_map_get_store_granularity**() - reads effective mapping granularity + +# SYNOPSIS # + +```c +#include + +enum pmem2_granularity { + PMEM2_GRANULARITY_BYTE, + PMEM2_GRANULARITY_CACHE_LINE, + PMEM2_GRANULARITY_PAGE, +}; +enum pmem2_granularity pmem2_map_get_store_granularity(struct pmem2_map *map); +``` + +# DESCRIPTION # + +The **pmem2_map_get_store_granularity**() function reads granularity of the created +mapping. The *map* parameter points to the structure describing mapping created +using the **pmem2_map_new**(3) function. Concept of the granularity is described in +**libpmem2**(7). + +# RETURN VALUE # + +The **pmem2_map_get_store_granularity**() function returns +a granularity of the mapped area. + +# SEE ALSO # + +**pmem2_map_new**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_new.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_new.3.md new file mode 100644 index 0000000000..e140bf4fe4 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_map_new.3.md @@ -0,0 +1,125 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_map_new.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019-2023, Intel Corporation) + +[comment]: <> (pmem2_map_new.3 -- man page for libpmem2 pmem2_map_new operation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_map_new**() - creates a mapping + +# SYNOPSIS # + +```c +#include + +struct pmem2_config; +struct pmem2_source; +struct pmem2_map; +int pmem2_map_new(struct pmem2_map **map_ptr, const struct pmem2_config *config, + const struct pmem2_source *source); +``` + +# DESCRIPTION # + +The **pmem2_map_new**() function creates a new mapping in the virtual address space +of the calling process. This function requires a configuration +*config* of the mapping and the data source *source*. + +Optionally, the mapping can be created at the offset of the virtual memory reservation +set in the configuration *config*. See **pmem2_config_set_vm_reservation**(3) for details. + +For a mapping to succeed, the *config* structure must have the granularity +parameter set to the appropriate level. See **pmem2_config_set_required_store_granularity**(3) +and **libpmem2**(7) for more details. + +If the **pmem2_map_new**() function succeeds in creating a new mapping it +instantiates a new *struct pmem2_map** object describing the mapping. The +pointer to this newly created object is stored in the user-provided variable +passed via the *map_ptr* pointer. If the mapping fails the variable pointed by +*map_ptr* will contain a NULL value and appropriate error value will be +returned. For a list of possible return values please see +[RETURN VALUE](#return-value). + +All *struct pmem2_map* objects created via the **pmem2_map_new**() function have to +be destroyed using the **pmem2_map_delete**() function. For details please see +**pmem2_map_delete**(3) manual page. + +# RETURN VALUE # + +The **pmem2_map_new**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_map_new**() can fail with the following errors: + +* **PMEM2_E_GRANULARITY_NOT_SET** - the store granularity for the mapping was +not set in the provided *config* structure. Please see **pmem2_config_set_required_store_granularity**(3) +and **libpmem2**(7). + +* **PMEM2_E_MAP_RANGE** - *offset* + *length* is too big to represent it using +*size_t* data type + +* **PMEM2_E_MAP_RANGE** - end of the mapping (*offset* + *length*) is outside +of the file. The file is too small. + +* **PMEM2_E_SOURCE_EMPTY** - mapped file has size equal to 0. + +* **PMEM2_E_MAPPING_EXISTS** - if the object exists before the function call. + +* **PMEM2_E_OFFSET_UNALIGNED** - argument unaligned, offset is not a multiple of +the alignment required for specific *\*source*. Please see +**pmem2_source_alignment**(3). + +* **PMEM2_E_LENGTH_UNALIGNED** - argument unaligned, length is not a multiple of +the alignment required for specific *\*source*. Please see +**pmem2_source_alignment**(3). + +* **PMEM2_E_SRC_DEVDAX_PRIVATE** - device DAX mapped with MAP_PRIVATE. + +* **PMEM2_E_ADDRESS_UNALIGNED** - when mapping device DAX to a virtual memory reservation +and the base mapping address (reservation address + reservation offset) is not aligned +to the device DAX granularity. Please see **pmem2_config_set_vm_reservation**(3). + +* **PMEM2_E_ADDRESS_UNALIGNED** - when mapping to a virtual memory reservation and the region +for the mapping exceeds reservation size. Please see **pmem2_config_set_vm_reservation**(3). + +* **PMEM2_E_NOSUPP** - when config-provided protection flags combination is not supported. + +* **PMEM2_E_NO_ACCESS** - there is a conflict between mapping protection and file opening mode. + +It can also return **-EACCES**, **-EAGAIN**, **-EBADF**, **-ENFILE**, +**-ENODEV**, **-ENOMEM**, **-EPERM**, **-ETXTBSY** from the underlying +**mmap**(2) function. It is used with and without **MAP_ANONYMOUS**. + +**-EACCES** may be returned only if the file descriptor points to an +append-only file. + +It can also return all errors from the underlying +**pmem2_source_size**() and **pmem2_source_alignment**() functions. + +# SEE ALSO # + +**mmap**(2), **open**(3), +**pmem2_config_set_required_store_granularity**(3), +**pmem2_source_alignment**(3), **pmem2_source_from_fd**(3), +**pmem2_source_size**(3), **pmem2_map_delete**(3), +**pmem2_config_set_vm_reservation**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_perror.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_perror.3.md new file mode 100644 index 0000000000..6a43159bbf --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_perror.3.md @@ -0,0 +1,45 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_perror.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_perror.3 -- man page for the error printing in libpmem2) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_perror**() - prints a descriptive error message to stderr + +# SYNOPSIS # + +```c +#include + +void pmem2_perror(const char *format, ...); +``` + +# DESCRIPTION # + +The **pmem2_perror**() function produces a message on standard error stream describing +the last error encountered during library call. + +**pmem2_perror**() takes a variable number of arguments. First, the argument string +*format* is printed - similarly to the **printf**(3), followed by a colon and a blank. +Then an error message retrieved from the **pmem2_errormsg**(), and a new-line. To see +how the error message is generated, please see **pmem2_errormsg**(3). + +# SEE ALSO # + +**libpmem2**(7), **perror**(3), **pmem2_errormsg**(3), **printf**(3) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_alignment.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_alignment.3.md new file mode 100644 index 0000000000..b688dc6120 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_alignment.3.md @@ -0,0 +1,76 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_source_alignment.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019-2023, Intel Corporation) + +[comment]: <> (pmem2_source_alignment.3 -- man page for pmem2_source_alignment) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_alignment**() - returns data source alignment + +# SYNOPSIS # + +```c +#include + +struct pmem2_source; +int pmem2_source_alignment(const struct pmem2_source *source, size_t *alignment); +``` + +# DESCRIPTION # + +The **pmem2_source_alignment**() function retrieves the alignment of offset and +length needed for **pmem2_map_new**(3) to succeed. The alignment is stored in +*\*alignment*. + +# RETURN VALUE # + +The **pmem2_source_alignment**() function returns 0 on success. +If the function fails, the *\*alignment* variable is left unmodified and a negative error code is returned. + +# ERRORS # + +The **pmem2_source_alignment**() can fail with the following errors: + +* **PMEM2_E_INVALID_ALIGNMENT_VALUE** - operating system returned unexpected +alignment value (eg. it is not a power of two). + +* **PMEM2_E_INVALID_FILE_TYPE** - file descriptor points to a character +device other than Device DAX. + +* **PMEM2_E_INVALID_ALIGNMENT_FORMAT** - kernel query for Device DAX alignment +returned data in invalid format. + +* -**errno** set by failing **fstat**(2), while trying to validate the file +descriptor. + +* -**errno** set by failing **realpath**(3), while trying to determine whether +fd points to a Device DAX. + +* -**errno** set by failing **read**(2), while trying to determine Device DAX's +alignment. + +* -**errno** set by failing **strtoull**(3), while trying to determine +Device DAX's alignment. + +# SEE ALSO # + +**errno**(3), **fstat**(2), **realpath**(3), **read**(2), **strtoull**(3), +**pmem2_config_new**(3), **pmem2_source_from_fd**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_id.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_id.3.md new file mode 100644 index 0000000000..926c4af50d --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_id.3.md @@ -0,0 +1,77 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_source_device_id.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_source_device_id.3 -- man page for pmem2_source_device_id) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_device_id**() - returns the unique identifier of a device + +# SYNOPSIS # + +```c +#include + +struct pmem2_source; +int pmem2_source_device_id(const struct pmem2_source *source, char *id, size_t *len); +``` + +# DESCRIPTION # + +The **pmem2_source_device_id**() function retrieves a unique identifier +of all NVDIMMs backing the data source. This function has two operating modes: + +* if *\*id* is NULL the function calculates a buffer length required for +storing the identifier of the *\*source* device and puts this length in *\*len* +The more hardware devices back the data source, the longer the length is. + +* if *\*id* is not NULL it must point to a buffer of length *\*len* provided by +the previous call to this function. +On success, **pmem2_source_device_id**() will store a unique identifier +of all hardware devices backing the data source. + +For details on how to use the unique identifier for detecting *the unsafe shutdown* +please refer to **libpmem2_unsafe_shutdown**(7) manual page. + +# RETURN VALUE # + +The **pmem2_source_device_id**() function returns 0 on success. +If the function fails, the *\*id* and *\*len* variables contents are left unmodified +and a negative error code is returned. + +# ERRORS # + +The **pmem2_source_device_id**() can fail with the following errors: + +* **PMEM2_E_BUFFER_TOO_SMALL** - the provided buffer of length *\*len* is too +small to store the full identifier of the backing devices. +* **PMEM2_E_NOSUPP** - the underlying platform does not expose hardware +identification. + +* -**errno** set by failing **fstat**(2), while trying to validate the file +descriptor. + +* -**errno** set by failing **ndctl_new**(), while trying to initiate a new +NDCTL library context. + +# SEE ALSO # + +**fstat**(2), **errno**(3), **malloc**(3), **libpmem2_unsafe_shutdown**(7), + and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_usc.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_usc.3.md new file mode 100644 index 0000000000..15b3335a49 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_device_usc.3.md @@ -0,0 +1,71 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_source_device_usc.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_source_device_usc.3 -- man page for pmem2_source_device_usc) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_device_usc**() - returns the *unsafe shutdown counter* value of a +device + +# SYNOPSIS # + +```c +#include + +struct pmem2_source; +int pmem2_source_device_usc(const struct pmem2_source *source, uint64_t *usc); +``` + +# DESCRIPTION # + +The **pmem2_source_device_usc**() function retrieves the sum of the +*unsafe shutdown count*(**USC**) values of all hardware devices backing +the data source and stores it in *\*usc*. + +Please refer to **libpmem2_unsafe_shutdown**(7) for detailed description on how +to properly consume this information. + +# RETURN VALUE # + +The **pmem2_source_device_usc**() function returns 0 on success. +If the function fails, the *\*usc* variable content is left unmodified +and a negative error code is returned. + +# ERRORS # + +The **pmem2_source_device_usc**() can fail with the following errors: + +* **PMEM2_E_NOSUPP** - the underlying platform does not expose unsafe shutdown +count information. + +* -**errno** set by failing **fstat**(2), while trying to validate the file +descriptor. + +* -**errno** set by failing **ndctl_new**(), while trying to initiate a new +NDCTL library context. + +* -**errno** set by failing **ndctl_dimm_get_dirty_shutdown**(), +while trying to obtain DIMM **USC** value. + +# SEE ALSO # + +**fstat**(2), **errno**(3), **malloc**(3), **libpmem2_unsafe_shutdown**(7), + and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_anon.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_anon.3.md new file mode 100644 index 0000000000..441adafb6d --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_anon.3.md @@ -0,0 +1,64 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_source_from_anon.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_source_from_anon.3 -- man page for pmem2_source_from_anon + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[CAVEATS](#caveats)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_from_anon**() - creates data source backed by anonymous memory pages + +# SYNOPSIS # + +```c +#include + +int pmem2_source_from_anon(struct pmem2_source **src, size_t size); +``` + +# DESCRIPTION # + +The **pmem2_source_from_anon**() function instantiates a new *struct pmem2_source* +object describing an anonymous data source. Mappings created using this function +are not backed by any file and are zero-initialized. + +The *size* argument for the function defines the length in bytes of the anonymous +source, as returned by **pmem2_source_size**(3). The application should set +this value so that it's greater than or equal to the size of any mapping created +with the anonymous source. + +The offset value for mapping is ignored. + +# RETURN VALUE # + +The **pmem2_source_from_anon**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_source_form_anon**() can fail with the following errors: + +* **-ENOMEM** - in case of insufficient +memory to allocate an instance of *struct pmem2_source*. + +# SEE ALSO # +**errno**(3), **pmem2_config_set_length**(3), **pmem2_map_new**(3), +**pmem2_source_size**(3), **pmem2_config_set_length**(3), **libpmem2**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_fd.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_fd.3.md new file mode 100644 index 0000000000..f6133f58f2 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_from_fd.3.md @@ -0,0 +1,75 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_source_from_fd.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019-2023, Intel Corporation) + +[comment]: <> (pmem2_source_from_fd.3 -- man page for pmem2_source_from_fd + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[CAVEATS](#caveats)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_from_fd**(), **pmem2_source_delete**() - creates or deletes an instance of persistent memory +data source + +# SYNOPSIS # + +```c +#include + +int pmem2_source_from_fd(struct pmem2_source *src, int fd); +int pmem2_source_delete(struct pmem2_source **src); +``` + +# DESCRIPTION # + +The **pmem2_source_from_fd**() function validates the file descriptor +and instantiates a new *struct pmem2_source** object describing the data source. + +*fd* must be opened with *O_RDONLY* or *O_RDWR* mode. + +If *fd* is invalid, then the function fails. + +The **pmem2_source_delete**() function frees *\*src* returned by **pmem2_source_from_fd**() +and sets *\*src* to NULL. If *\*src* is NULL, no operation is performed. + +# RETURN VALUE # + +The **pmem2_source_from_fd**() function return 0 on success +or a negative error code on failure. + +The **pmem2_source_delete**() function always returns 0. + +# ERRORS # + +The **pmem2_source_from_fd**() function can fail with the following errors: + + * **PMEM2_E_INVALID_FILE_HANDLE** - *fd* is not an open and valid file descriptor. + + * **PMEM2_E_INVALID_FILE_HANDLE** - *fd* is opened in O_WRONLY mode. + + * **PMEM2_E_INVALID_FILE_TYPE** - *fd* points to a directory, block device, pipe, or socket. + + * **PMEM2_E_INVALID_FILE_TYPE** - *fd* points to a character device other than Device DAX. + +The **pmem2_source_from_fd**() function can also return **-ENOMEM** +in case of insufficient memory to allocate an instance of *struct pmem2_source*. + +# SEE ALSO # + +**errno**(3), **pmem2_map_new**(3), **libpmem2**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_get_fd.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_get_fd.3.md new file mode 100644 index 0000000000..3a33612fd4 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_get_fd.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: ["pmem2_source_get_fd.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_source_get_fd.3 -- man page for pmem2_source_get_fd + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_get_fd**() - reads file descriptor of the data source + +# SYNOPSIS # + +```c +#include + +int pmem2_source_get_fd(const struct pmem2_source *src, int *fd); +``` + +# DESCRIPTION # + +The **pmem2_source_get_fd**() function reads the file descriptor of +*struct pmem2_source** object describing the data source and returns it +by *fd* parameter. + +# RETURN VALUE # + +The **pmem2_source_get_fd**() function returns 0 on success +or a negative error code on failure. + +# ERRORS # + +The **pmem2_source_get_fd**() can fail with the following errors: + +* **PMEM2_E_FILE_DESCRIPTOR_NOT_SET** - in case of an instance of +*struct pmem2_source* that does not come from source type that +support file descriptors, eg. anonymous data source. + +# SEE ALSO # + +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_numa_node.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_numa_node.3.md new file mode 100644 index 0000000000..da3369c764 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_numa_node.3.md @@ -0,0 +1,70 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_source_numa_node.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2023, Intel Corporation) + +[comment]: <> (pmem2_source_numa_node.3 -- man page for pmem2_source_numa_node) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[CAVEATS](#caveats)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_numa_node**() - returns data source numa node + +# SYNOPSIS # + +```c +#include + +struct pmem2_source; +int pmem2_source_numa_node(const struct pmem2_source *source, int *numa_node); +``` + +# DESCRIPTION # + +The **pmem2_source_numa_node**() function retrieves the numa node of the given data source. +The numa node can be used to, e.g., pin threads to near-memory cores. The numa node is stored in *\*numa_node*. +It is the same value that is shown as `numa_node` in `ndctl list -v`. + +# RETURN VALUE # + +The **pmem2_source_numa_node**() function returns 0 on success. +If the function fails, the *\*numa_node* variable is left unmodified and a negative error code is returned. + +# ERRORS # + +The **pmem2_source_numa_node**() can fail with the following errors: + +* **PMEM2_E_NOSUPP** - source type or operating system not supported (see #caveats for details.) + +* **PMEM2_E_DAX_REGION_NOT_FOUND** - no **ndctl_region** could be determined for the source. + +* **PMEM2_E_INVALID_FILE_TYPE** - if the source points to a directory. + +* -**errno** set by failing **ndctl_new**, while trying to create a new context. + +# CAVEATS # + +This call requires **libndctl** to retrieve the numa information. +It only works for sources that are actually located on persistent memory, i.e., devdax or fsdax. +As anonymous sources are not backed by files on persistent memory, this method is not supported for them. +It also does not work under systems without **libndctl**. + +# SEE ALSO # + +**errno**(3), **ndctl_new**(3), **pmem2_source_from_fd**(3), +**libpmem2**(7), **libndctl**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_pread_mcsafe.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_pread_mcsafe.3.md new file mode 100644 index 0000000000..fc08ffa047 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_pread_mcsafe.3.md @@ -0,0 +1,83 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_source_pread_mcsafe.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2021-2023, Intel Corporation) + +[comment]: <> (pmem2_source_pread_mcsafe.3 -- man page for libpmem2 machine safe read/write operations) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_pread_mcsafe**(), **pmem2_source_pwrite_mcsafe**() - read source +contents or write to the source in a safe manner + +# SYNOPSIS # + +```c +#include + +struct pmem2_source; +int pmem2_source_pread_mcsafe(struct pmem2_source *src, void *buf, size_t size, + size_t offset); +int pmem2_source_pwrite_mcsafe(struct pmem2_source *src, void *buf, size_t size, + size_t offset); +``` + +# DESCRIPTION # + +The **pmem2_source_pread_mcsafe**() function reads *size* bytes from the source *src* +starting at offset *offset* into the buffer *buf*. +The **pmem2_source_pwrite_mcsafe**() function writes *size* bytes from the buffer *buf* +to the source *src* starting at the offset *offset*. + +Above functions are capable of detecting bad blocks and handling the *SIGBUS* signal thrown +when accessing a bad block. When a bad block is encountered, **pmem2_source_pread_mcsafe**() +and **pmem2_source_pwrite_mcsafe**() functions return corresponding error. A signal handler +for *SIGBUS* signal is registered using **sigaction**(2) for the running time of those operations. +This capability is limited to POSIX systems. + +For bad block detection and clearing, see **pmem2_badblock_context_new**(3), +**pmem2_badblock_next**(3) and **pmem2_badblock_clear**(3). + +# RETURN VALUE # + +The **pmem2_source_pread_mcsafe**() and **pmem2_source_pwrite_mcsafe**() functions +return 0 on success or a negative error code on failure. + +# ERRORS # + +The **pmem2_source_pread_mcsafe**() and **pmem2_source_pwrite_mcsafe**() can fail +with the following errors: + +* **PMEM2_E_IO_FAIL** - a physical I/O error occurred during the read/write operation, +a possible bad block encountered. + +* **PMEM2_E_LENGTH_OUT_OF_RANGE** - read/write operation size *size* from +offset *offset* goes beyond the file length. + +* **PMEM2_E_SOURCE_TYPE_NOT_SUPPORTED** - read/write operation doesn't support +provided source, only sources created with **pmem2_source_from_fd**(3) is supported. + +Those operations can also return all errors from the underlying **pread**(2), +**pwrite**(2), **sigaction**(2) functions. + +# SEE ALSO # + +**pread**(2), **pwrite**(2), **ReadFile**(), **WriteFile**(), +**pmem2_badblock_clear**(3), **pmem2_badblock_context_new**(3), +**pmem2_badblock_next**(3), **pmem2_source_from_fd**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_size.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_size.3.md new file mode 100644 index 0000000000..3a16370100 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_source_size.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: ["pmem2_source_size.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2019-2023, Intel Corporation) + +[comment]: <> (pmem2_source_size.3 -- man page for pmem2_source_size) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_source_size**() - returns the size of the data source + +# SYNOPSIS # + +```c +#include + +struct pmem2_source; +int pmem2_source_size(const struct pmem2_source *source, size_t *size); +``` + +# DESCRIPTION # + +The **pmem2_source_size**() function retrieves the size of the file +in bytes pointed by file descriptor stored in the *source* and puts +it in *\*size*. + +This function hides the quirkiness of Device DAX size detection. + +# RETURN VALUE # + +The **pmem2_source_size**() function returns 0 on success. +If the function fails, the *\*size* variable is left unmodified +and a negative error code is returned. + +# ERRORS # + +The **pmem2_source_size**() can fail with the following errors: + +* **PMEM2_E_INVALID_FILE_HANDLE** - source contains an invalid file handle. + +* **PMEM2_E_INVALID_FILE_TYPE** - file descriptor points to a directory, +block device, pipe, or socket. + +* **PMEM2_E_INVALID_FILE_TYPE** - file descriptor points to a character +device other than Device DAX. + +* **PMEM2_E_INVALID_SIZE_FORMAT** - kernel query for Device DAX size +returned data in invalid format. + +* -**errno** set by failing **fstat**(2), while trying to validate the file +descriptor. + +* -**errno** set by failing **realpath**(3), while trying to determine whether +fd points to a Device DAX. + +* -**errno** set by failing **open**(2), while trying to determine Device DAX's +size. + +* -**errno** set by failing **read**(2), while trying to determine Device DAX's +size. + +* -**errno** set by failing **strtoull**(3), while trying to determine +Device DAX's size. + +# SEE ALSO # + +**errno**(3), **fstat**(2), **realpath**(3), **open**(2), **read**(2), +**strtoull**(3), **pmem2_config_new**(3), **libpmem2**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_extend.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_extend.3.md new file mode 100644 index 0000000000..e4770d3ac4 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_extend.3.md @@ -0,0 +1,98 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_vm_reservation_extend.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2021-2022, Intel Corporation) + +[comment]: <> (pmem2_vm_reservation_extend.3 -- man page for libpmem2 pmem2_vm_reservation_extend and pmem2_vm_reservation_shrink operations) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_vm_reservation_extend**(), **pmem2_vm_reservation_shrink**() - extends and shrinks +existing virtual memory reservation + +# SYNOPSIS # + +```c +#include + +struct pmem2_vm_reservation; +int pmem2_vm_reservation_extend(struct pmem2_vm_reservation *rsv, size_t size); +int pmem2_vm_reservation_shrink(struct pmem2_vm_reservation *rsv, size_t offset, + size_t size); +``` + +# DESCRIPTION # + +The **pmem2_vm_reservation_extend**() function extends an existing virtual memory +reservation by the given *size*. For the function to succeed the size has to be aligned +to an appropriate allocation granularity. + +If the **pmem2_vm_reservation_extend**() succeeds in extending a reservation, it provides +placeholder virtual memory range that starts from an address at the end of the old reservation. +Mappings made to the reservation before extending are preserved. + +The **pmem2_vm_reservation_shrink**() function shrinks the reservation by a region specified +by *offset* into the reservation and the *size*. For the function to succeed the *size* and +*offset* variables have to be aligned to an appropriate allocation granularity. The region +formed by *offset* and *size* has to belong to the reservation, be empty and it needs to cover +the beginning or the end of the reservation. +Shrinking reservation from the middle or shrinking the whole reservation is not supported. + +If the **pmem2_vm_reservation_shrink**() succeeds in shrinking a reservation, it releases +placeholder virtual memory range that was designated by *offset* and *size* variables. +Mappings made to the reservation before shrinking are preserved. + +If either of those functions fails, reservation will be left as it was and appropriate error +value will be returned. + +# RETURN VALUE # + +The **pmem2_vm_reservation_extend**() and **pmem2_vm_reservation_shrink**() functions return 0 +on success or a negative error code on failure. + +# ERRORS # + +The **pmem2_vm_reservation_extend**() function can fail with the following errors: + +* **PMEM2_E_MAPPING_EXISTS** - the range that the reservation would be extended by is already occupied +by an existing mapping. + +It can also return **-EAGAIN**, **-ENOMEM** from the underlying **mmap**(2) function. + +The **pmem2_vm_reservation_shrink**() function can fail with the following errors: + +* **PMEM2_E_OFFSET_UNALIGNED** - provided offset isn't aligned to an appropriate allocation granularity. + +* **PMEM2_E_LENGTH_UNALIGNED** - provided size isn't aligned to an appropriate allocation granularity. + +* **PMEM2_E_OFFSET_OUT_OF_RANGE** - provided offset is out of reservation range available to be shrunk. + +* **PMEM2_E_LENGTH_OUT_OF_RANGE** - provided size is out of reservation range available to be shrunk. + +* **PMEM2_E_NOSUPP** - interval designated by *offset* and *size* variables covers only the +middle or the whole reservation range. + +* **PMEM2_VM_RESERVATION_NOT_EMPTY** - interval designated by *offset* and *size* variable is not +empty. + +It can also return **-EAGAIN** and **-ENOMEM** from the underlying **munmap**(2) function. + +# SEE ALSO # + +**pmem2_vm_reservation_new**(3), **pmem2_config_set_vm_reservation**(3), +**libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_address.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_address.3.md new file mode 100644 index 0000000000..24eb258548 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_address.3.md @@ -0,0 +1,47 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_vm_reservation_get_address.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_vm_reservation_get_address.3 -- man page for libpmem2 pmem2_vm_reservation_get_address operation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_vm_reservation_get_address**() - reads address of the virtual memory reservation + +# SYNOPSIS # + +```c +#include + +void *pmem2_vm_reservation_get_address(struct pmem2_vm_reservation *rsv); +``` + +# DESCRIPTION # + +The **pmem2_vm_reservation_get_address**() function reads address of the created virtual memory +reservation. The *rsv* parameter points to the structure describing the reservation created using +the **pmem2_vm_reservation_new**(3) function. + +# RETURN VALUE # + +The **pmem2_vm_reservation_get_address**() function returns a pointer to the virtual memory +reservation area. + +# SEE ALSO # + +**pmem2_vm_reservation_new**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_size.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_size.3.md new file mode 100644 index 0000000000..9743a5ddff --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_get_size.3.md @@ -0,0 +1,46 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_vm_reservation_get_size.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020, Intel Corporation) + +[comment]: <> (pmem2_vm_reservation_get_size.3 -- man page for libpmem2 virtual memory reservation operation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_vm_reservation_get_size**() - reads virtual memory reservation size + +# SYNOPSIS # + +```c +#include + +size_t pmem2_vm_reservation_get_size(struct pmem2_vm_reservation *rsv); +``` + +# DESCRIPTION # + +The **pmem2_vm_reservation_get_size**() function reads size of the created virtual memory +reservation. The *rsv* parameter points to the structure describing virtual memory reservation +created using the **pmem2_vm_reservation_new**(3) function. + +# RETURN VALUE # + +The **pmem2_vm_reservation_get_size**() function returns a size of the virtual reservation area. + +# SEE ALSO # + +**pmem2_vm_reservation_new**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_map_find.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_map_find.3.md new file mode 100644 index 0000000000..df813326ab --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_map_find.3.md @@ -0,0 +1,88 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_vm_reservation_map_find.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2021-2022, Intel Corporation) + +[comment]: <> (pmem2_vm_reservation_map_find.3 -- man page for libpmem2 pmem2_vm_reservation_map_find operation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_vm_reservation_map_find**(), **pmem2_vm_reservation_map_find_prev**(), +**pmem2_vm_reservation_map_find_next**(), **pmem2_vm_reservation_map_find_first**() and +**pmem2_vm_reservation_map_find_last**() - search for the mapping located at the +desirable location + +# SYNOPSIS # + +```c +#include + +struct pmem2_map; +struct pmem2_vm_reservation; +int pmem2_vm_reservation_map_find(struct pmem2_vm_reservation *rsv, + size_t reserv_offset, size_t len, struct pmem2_map **map_ptr); +int pmem2_vm_reservation_map_find_prev(struct pmem2_vm_reservation *rsv, + struct pmem2_map *map, struct pmem2_map **prev_map); +int pmem2_vm_reservation_map_find_next(struct pmem2_vm_reservation *rsv, + struct pmem2_map *map, struct pmem2_map **next_map); +int pmem2_vm_reservation_map_find_first(struct pmem2_vm_reservation *rsv, + struct pmem2_map **first_map); +int pmem2_vm_reservation_map_find_last(struct pmem2_vm_reservation *rsv, + struct pmem2_map **last_map); +``` + +# DESCRIPTION # +Mappings are inserted to the virtual memory reservation in the order of their virtual +address space location. First mapping represents the earliest mapping in the virtual +address space contained in a reservation, whereas the last mapping represents the last one. + +The **pmem2_vm_reservation_map_find**() function searches for the earliest mapping, +stored in the virtual memory reservation, intersecting with the interval defined by +*reserv_offset* and *len* variables and returns it via *map_ptr* variable. + +**pmem2_vm_reservation_map_find_prev**() function searches for the map previous +to the provided *map* and returns it via provided *prev_map* variable. + +**pmem2_vm_reservation_map_find_next**() function searches for the map next after +the provided *map* and returns it via *next_map* variable. + +**pmem2_vm_reservation_map_find_first**() function searches for the first map in +the reservation and returns it via provided *first_map* variable. + +**pmem2_vm_reservation_map_find_last**() function searches for the last map in +the reservation and returns it via provided *last_map* variable. +# RETURN VALUE # + +The **pmem2_vm_reservation_map_find**(), **pmem2_vm_reservation_map_find_prev**(), +**pmem2_vm_reservation_map_find_next**(), **pmem2_vm_reservation_map_find_first**() and +**pmem2_vm_reservation_map_find_last**() return 0 on success or a negative error on failure. + +It passes an address to the found mapping via user provided *map* pointer variable +on success, otherwise it passes *NULL* value when no mapping was found. + +# ERRORS # + +The **pmem2_vm_reservation_map_find**(), **pmem2_vm_reservation_map_find_prev**(), +**pmem2_vm_reservation_map_find_next**(), **pmem2_vm_reservation_map_find_first**() and +**pmem2_vm_reservation_map_find_last**() can fail with the following errors: + +- **PMEM2_E_MAPPING_NOT_FOUND** - no mapping found at the desirable location of the reservation + +# SEE ALSO # + +**libpmem2**(7), and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_new.3.md b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_new.3.md new file mode 100644 index 0000000000..f219dc340c --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmem2/pmem2_vm_reservation_new.3.md @@ -0,0 +1,96 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem2_vm_reservation_new.3.html"] +title: "libpmem2 | PMDK" +header: "pmem2 API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2020-2021, Intel Corporation) + +[comment]: <> (pmem2_vm_reservation_new.3 -- man page for libpmem2 virtual memory reservation API) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmem2_vm_reservation_new**(), **pmem2_vm_reservation_delete**() - creates or deletes +an instance of virtual memory reservation + +# SYNOPSIS # + +```c +#include + +struct pmem2_vm_reservation; +int pmem2_vm_reservation_new(struct pmem2_vm_reservation **rsv_ptr, + void *addr, size_t size); +int pmem2_vm_reservation_delete(struct pmem2_vm_reservation **rsv_ptr); +``` + +# DESCRIPTION # + +The **pmem2_vm_reservation_new**() function creates a new blank mapping in the +virtual address space of the calling process. Reservation serves as a placeholder +of a given size on which sources can be mapped. + +For the function to succeed, the *addr* must be either aligned to an appropriate +allocation granularity or **NULL**, the size always has to be aligned to an +appropriate OS allocation granularity. + +**libpmem2**(7) library chooses the largest page alignment for the reservation based on *size*. +If the chosen alignment is different than the OS allocation granularity, then the underlying +size of the reservation can be bigger than the value presented to the user. Largest page alignment +functionality is limited to POSIX systems. + +If the **pmem2_vm_reservation_new**() succeeds in creating a reservation, it instantiates a new +**struct pmem2_vm_reservation** object describing the reservation. The pointer to this object +is stored in the user-provided variable via the *rsv_ptr* pointer. If the function +fails, an appropriate error value will be returned. For a list of possible return +values please see [RETURN VALUE](#return-value) + +After instantiating an object via the **pmem2_vm_reservation_new**() function, it +may be disposed of using the **pmem2_vm_reservation_delete**() function. + +The **pmem2_vm_reservation_delete**() function destroys the object describing +the reservation and unmaps virtual memory region +the *struct pmem2_vm_reservation** had assigned during the initialization. +For the delete function to succeed, it is required that the reservation passed via +the *rsv_ptr* pointer does not contain any mappings. + +# RETURN VALUE # + +The **pmem2_vm_reservation_new**() and **pmem2_vm_reservation_delete**() functions return 0 +on success or a negative error code on failure. + +The function returns 0 on success or a negative error code on failure. + +# ERRORS # + +The **pmem2_vm_reservation_new**() function can fail with the following errors: + +* **PMEM2_E_ADDRESS_UNALIGNED** - argument *addr* is not aligned to the appropriate +allocation granularity. + +* **PMEM2_E_MAPPING_EXISTS** - mapping already exists in the range (*addr*, *addr* + *size*). + +It can also return **-EAGAIN**, **-ENOMEM** from the underlying **mmap**(2) function and **-ENOMEM** +in case of insufficient memory to allocate an instance of *struct pmem2_vm_reservation*. + +The **pmem2_vm_reservation_delete**() function can fail with the following errors: + +* **PMEM2_E_RESERVATION_NOT_EMPTY** - reservation contains mappings. + +It can also return errors from the underlying **munmap**(2) function. + +# SEE ALSO # + +**pmem2_config_set_vm_reservation**(3), **libpmem2**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/libpmemobj.7.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/libpmemobj.7.md new file mode 100644 index 0000000000..3c089ae708 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/libpmemobj.7.md @@ -0,0 +1,237 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["libpmemobj.7.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (libpmemobj.7 -- man page for libpmemobj) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[LIBRARY API VERSIONING](#library-api-versioning-1)
+[MANAGING LIBRARY BEHAVIOR](#managing-library-behavior-1)
+[DEBUGGING AND ERROR HANDLING](#debugging-and-error-handling)
+[EXAMPLE](#example)
+[ACKNOWLEDGEMENTS](#acknowledgements)
+[SEE ALSO](#see-also)
+ +# NAME # + +**libpmemobj** - persistent memory transactional object store + +# SYNOPSIS # + +```c +#include +cc -std=gnu99 ... -lpmemobj -lpmem +``` + +##### Library API versioning: ##### + +```c +const char *pmemobj_check_version( + unsigned major_required, + unsigned minor_required); +``` + +##### Managing library behavior: ##### + +```c +void pmemobj_set_funcs( + void *(*malloc_func)(size_t size), + void (*free_func)(void *ptr), + void *(*realloc_func)(void *ptr, size_t size), + char *(*strdup_func)(const char *s)); +``` + +##### Error handling: ##### + +```c +const char *pmemobj_errormsg(void); +``` + +##### Other library functions: ##### + +A description of other **libpmemobj** functions can be found on the following +manual pages: + ++ control and statistics: **pmemobj_ctl_get**(3) + ++ create, open, close and validate: **pmemobj_open**(3) + ++ low-level memory manipulation: **pmemobj_memcpy_persist**(3) + ++ locking: **pmemobj_mutex_zero**(3) + ++ persistent object identifier: **OID_IS_NULL**(3) + ++ type-safety: **TOID_DECLARE**(3) + ++ layout declaration: **POBJ_LAYOUT_BEGIN**(3) + ++ non-transactional atomic allocations: **pmemobj_alloc**(3) + ++ root object management: **pmemobj_root**(3) + ++ object containers: **pmemobj_first**(3) + ++ non-transactional persistent atomic circular doubly-linked list: +**pmemobj_list_insert**(3), **POBJ_LIST_HEAD**(3) + ++ transactional object manipulation: **pmemobj_tx_begin**(3), +**pmemobj_tx_add_range**(3), **pmemobj_tx_alloc**(3) + ++ delayed atomicity actions: **pmemobj_action**(3) (EXPERIMENTAL) + +# DESCRIPTION # + +**libpmemobj** provides a transactional object store in *persistent memory* +(pmem) for applications that require transactions and persistent memory +management using direct access storage (DAX), which is storage that supports +load/store access without paging blocks from a block storage device. Some types +of *non-volatile memory DIMMs* (NVDIMMs) provide this type of byte addressable +access to storage. A *persistent memory aware file system* is typically used to +expose the direct access to applications. Memory mapping a file from this type +of file system results in load/store, non-paged access to pmem. **libpmemobj** +builds on this type of memory mapped file using the low-level pmem support +provided by **libpmem**(7), handling the transactional updates, flushing +changes to persistence, and managing recovery for the application. + +**libpmemobj** requires the **-std=gnu99** compilation flag to +build properly. + +**libpmemobj** is one of a collection of persistent memory libraries available. +The other is **libpmem**(7), low-level persistent memory support. + +Under normal usage, **libpmemobj** will never print messages or intentionally +cause the process to exit. The only exception to this is the debugging +information, when enabled, as described under **DEBUGGING AND ERROR HANDLING**, +below. + +# LIBRARY API VERSIONING # + +This section describes how the library API is versioned, +allowing applications to work with an evolving API. + +The **pmemobj_check_version**() function is used to see if the installed +**libpmemobj** supports the version of the library API required by an +application. The easiest way to do this is for the application to supply +the compile-time version information, supplied by defines in +**\**, like this: + +```c +reason = pmemobj_check_version(PMEMOBJ_MAJOR_VERSION, PMEMOBJ_MINOR_VERSION); +if (reason != NULL) { + /* version check failed, reason string tells you why */ +} +``` + +Any mismatch in the major version number is considered a failure, but a library +with a newer minor version number will pass this check since increasing minor +versions imply backwards compatibility. + +An application can also check specifically for the existence of an interface +by checking for the version where that interface was introduced. These versions +are documented in this man page as follows: unless otherwise specified, all +interfaces described here are available in version 1.0 of the library. Interfaces +added after version 1.0 will contain the text *introduced in version x.y* in +the section of this manual describing the feature. + +On success, **pmemobj_check_version**() returns NULL. Otherwise, the return +value is a static string describing the reason the version check failed. The +string returned by **pmemobj_check_version**() must not be modified or freed. + +# MANAGING LIBRARY BEHAVIOR # + +The **pmemobj_set_funcs**() function allows an application to override memory +allocation calls used internally by **libpmemobj**. Passing in NULL for any of +the handlers will cause the **libpmemobj** default function to be used. The +library does not make heavy use of the system malloc functions, but it does +allocate approximately 4-8 kilobytes for each memory pool in use. + +By default, **libpmemobj** supports up to 1024 parallel +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 # + +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 +from **pmemobj_errormsg**(). This function returns a pointer to a static buffer +containing the last error message logged for the current thread. If *errno* +was set, the error message may include a description of the corresponding +error code as returned by **strerror**(3). The error message buffer is +thread-local; errors encountered in one thread do not affect its value in +other threads. The buffer is never cleared by any library function; its +content is significant only when the return value of the immediately preceding +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. + +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 +that impact performance and never logs any trace information or performs any +run-time assertions. + +A second version of **libpmemobj**, accessed when a program uses the libraries +under **/usr/lib/pmdk_debug**, contains run-time assertions and trace points. +The typical way to access the debug version is to set the environment variable +**LD_LIBRARY_PATH** to **/usr/lib/pmdk_debug** or **/usr/lib64/pmdk_debug**, +as appropriate. Debugging output is controlled using the following environment +variables. These variables have no effect on the non-debug version of the library. + ++ **PMEMOBJ_LOG_LEVEL** + +The value of **PMEMOBJ_LOG_LEVEL** 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. + ++ **1** - Additional details on any errors detected are logged, +in addition to returning the *errno*-based errors as usual. +The same information may be retrieved using **pmemobj_errormsg**(). + ++ **2** - A trace of basic operations is logged. + ++ **3** - Enables a very verbose amount of function call +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*. + ++ **PMEMOBJ_LOG_FILE** + +Specifies the name of a file where all logging information should be written. +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*. + +See also **libpmem**(7) to get information +about other environment variables affecting **libpmemobj** behavior. + +# EXAMPLE # + +See for examples using the **libpmemobj** API. + +# ACKNOWLEDGEMENTS # + +**libpmemobj** builds on the persistent memory programming model recommended +by the SNIA NVM Programming Technical Work Group: + + +# SEE ALSO # + +**OID_IS_NULL**(3), **pmemobj_alloc**(3), **pmemobj_ctl_exec**(3), **pmemobj_ctl_get**(3), **pmemobj_ctl_set**(3), **pmemobj_first**(3), **pmemobj_list_insert**(3), **pmemobj_memcpy_persist**(3), **pmemobj_mutex_zero**(3), **pmemobj_open**(3), **pmemobj_root**(3), **pmemobj_tx_add_range**(3), **pmemobj_tx_alloc**(3), **pmemobj_tx_begin**(3), **POBJ_LAYOUT_BEGIN**(3), **POBJ_LIST_HEAD**(3), **strerror**(3), **TOID_DECLARE**(3), **libpmem**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/oid_is_null.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/oid_is_null.3.md new file mode 100644 index 0000000000..c89e9b903f --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/oid_is_null.3.md @@ -0,0 +1,189 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["oid_is_null.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (oid_is_null.3 -- man page for persistent object identifier and functions) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[NOTES](#notes)
+[SEE ALSO](#see-also)
+ +# NAME # + +**OID_IS_NULL**(), **OID_EQUALS**(), +**pmemobj_direct**(), **pmemobj_oid**(), +**pmemobj_type_num**(), **pmemobj_pool_by_oid**(), +**pmemobj_pool_by_ptr**() - functions that allow mapping +operations between object addresses, object handles, oids or type numbers + +# SYNOPSIS # + +```c +#include + +OID_IS_NULL(PMEMoid oid) +OID_EQUALS(PMEMoid lhs, PMEMoid rhs) + +void *pmemobj_direct(PMEMoid oid); +PMEMoid pmemobj_oid(const void *addr); +uint64_t pmemobj_type_num(PMEMoid oid); +PMEMobjpool *pmemobj_pool_by_oid(PMEMoid oid); +PMEMobjpool *pmemobj_pool_by_ptr(const void *addr); +void *pmemobj_volatile(PMEMobjpool *pop, struct pmemvlt *vlt, + size_t size, void *ptr, + int (*constr)(void *ptr, void *arg), void *arg); (EXPERIMENTAL) +``` + +# DESCRIPTION # + +Each object stored in a persistent memory pool is represented by an object +handle of type *PMEMoid*. In practice, such a handle is a unique Object +IDentifier (*OID*) of global scope, which means that two objects from +different pools will never have the same *OID*. The special **OID_NULL** +macro defines a NULL-like handle that does not represent any object. +The size of a single object is limited by **PMEMOBJ_MAX_ALLOC_SIZE**. +Thus an allocation with a requested size greater than this value will fail. + +An *OID* cannot be used as a direct pointer to an object. Each time +the program attempts to read or write object data, it must obtain the current +memory address of the object by converting its *OID* into a pointer. + +In contrast to the memory address, the *OID* value for given object does not +change during the life of an object (except for *realloc*), and remains +valid after closing and reopening the pool. For this reason, if an object +contains a reference to another persistent object, for example, to build +some kind of a linked data structure, the reference must be an *OID* and not +a memory address. + +**pmemobj_direct**() returns a pointer to the *PMEMoid* object with +handle *oid*. + +**pmemobj_oid**() returns a *PMEMoid* handle to the object pointed +to by *addr*. + +**pmemobj_type_num**() returns the type number of the *PMEMoid* object with +handle *oid*. + +**pmemobj_pool_by_oid**() returns a *PMEMobjpool*\* handle to the pool +containing the *PMEMoid* object with handle *oid*. + +**pmemobj_pool_by_ptr**() returns a *PMEMobjpool*\* handle to the pool +containing the address *addr*. + +At the time of allocation (or reallocation), each object may be assigned +a number representing its type. Such a *type number* may be used to arrange the +persistent objects based on their actual user-defined structure type, thus +facilitating implementation of a simple run-time type safety mechanism. This +also allows iterating through all the objects of a given type that are stored +in the persistent memory pool. See **pmemobj_first**(3) for more information. + +The **OID_IS_NULL**() macro checks if *PMEMoid* represents a NULL object. + +The **OID_EQUALS**() macro compares two *PMEMoid* objects. + +For special cases where volatile (transient) variables need to be stored on +persistent memory, there's a mechanism composed of *struct pmemvlt* type and +**pmemobj_volatile()** function. To use it, the *struct pmemvlt* needs to +be placed in the neighborhood of transient data region. The *PMEMvlt* macro +can be used to construct such a region. +The *struct pmemvlt* must be zeroed prior to use. This can be easily done in +object constructor or in a transaction directly after an allocation. +When the **pmemobj_volatile()** function is called on a *struct pmemvlt*, +it will return the pointer to the data and it will ensure that the provided +constructor function is called exactly once in the current instance of the +pmemobj pool. +The constructor is called with the *ptr* pointer to the data, and this function +will return the same pointer if the constructor returns *0*, otherwise NULL is +returned. The *size* argument must accurately describe the total size of the +volatile memory region that will be accessed. Calling **pmemobj_volatile()** +on the same region with different sizes is undefined behavior. +For this mechanism to be effective, all accesses to transient variables must +go through it, otherwise there's a risk of the constructor not being called +on the first load. +Maintaining transient state on persistent memory is challenging due to +difficulties with dynamic resources acquisition and subsequent resource release. +For example, one needs to consider what happens with volatile state of an object +which is being freed inside of a transaction, especially with regards to the +possibility of an abort. +It's generally recommended to entirely separate the persistent and transient +states, and when it's not possible, to only store types which do not require +lifecycle management (i.e., primitive types) inside of volatile regions. + +# RETURN VALUE # + +The **pmemobj_direct**() function returns a pointer to the object represented +by *oid*. If *oid* is **OID_NULL**, **pmemobj_direct**() returns NULL. + +The **pmemobj_oid**() function returns a *PMEMoid* handle to the object pointed +to by *addr*. If *addr* is not from within a pmemobj pool, **OID_NULL** is +returned. If *addr* is not the start of an object (does not point to the +beginning of a valid allocation), the resulting *PMEMoid* can be safely used +only with: + ++ **pmemobj_pool_by_oid**() + ++ **pmemobj_direct**() + ++ **pmemobj_tx_add_range**(3) + +The **pmemobj_type_num**() function returns the type number of the object +represented by *oid*. + +The **pmemobj_pool_by_oid**() function returns a handle to the pool that +contains the object represented by *oid*. If the pool is not open or +*oid* is **OID_NULL**, **pmemobj_pool_by_oid**() returns NULL. + +The **pmemobj_pool_by_ptr**() function returns a handle to the pool that +contains the address, or NULL if the address does not belong to any open pool. + +# NOTES # + +For performance reasons the **pmemobj_direct**() function is inlined by default. +To use the non-inlined variant of **pmemobj_direct**(), +define **PMEMOBJ_DIRECT_NON_INLINE** prior to the *\#include* of **\**, +either with *\#define* or with the *\-D* option to the compiler. + +# EXAMPLES # + +The following code shows how to store transient variables on persistent memory. + +```c +struct my_data { + PMEMvlt(uint64_t) foo; + uint64_t bar; +}; + +int +my_data_constructor(void *ptr, void *arg) +{ + uint64_t *foo = ptr; + *foo = 0; + + return 0; +} + +PMEMobjpool *pop = ...; + +struct my_data *data = D_RW(...); + +uint64_t *foo = pmemobj_volatile(pop, &data->foo.vlt, &data->foo.value, + my_data_constructor, NULL); + +assert(*foo == 0); +``` + +# SEE ALSO # + +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_action.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_action.3.md new file mode 100644 index 0000000000..0e75fac755 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_action.3.md @@ -0,0 +1,191 @@ +--- +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_action.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2019, Intel Corporation) + +[comment]: <> (pmemobj_action.3 -- Delayed atomicity actions) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[EXAMPLES](#examples)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_reserve**(), **pmemobj_xreserve**(), **pmemobj_defer_free**(), +**pmemobj_set_value**(), **pmemobj_publish**(), **pmemobj_tx_publish**(), +**pmemobj_tx_xpublish**(), **pmemobj_cancel**(), **POBJ_RESERVE_NEW**(), +**POBJ_RESERVE_ALLOC**(), **POBJ_XRESERVE_NEW**(),**POBJ_XRESERVE_ALLOC**() +- Delayed atomicity actions (EXPERIMENTAL) + +# SYNOPSIS # + +```c +#include + +PMEMoid pmemobj_reserve(PMEMobjpool *pop, struct pobj_action *act, + size_t size, uint64_t type_num); (EXPERIMENTAL) +PMEMoid pmemobj_xreserve(PMEMobjpool *pop, struct pobj_action *act, + size_t size, uint64_t type_num, uint64_t flags); (EXPERIMENTAL) +void pmemobj_defer_free(PMEMobjpool *pop, PMEMoid oid, struct pobj_action *act); +void pmemobj_set_value(PMEMobjpool *pop, struct pobj_action *act, + uint64_t *ptr, uint64_t value); (EXPERIMENTAL) +int pmemobj_publish(PMEMobjpool *pop, struct pobj_action *actv, + size_t actvcnt); (EXPERIMENTAL) +int pmemobj_tx_publish(struct pobj_action *actv, size_t actvcnt); (EXPERIMENTAL) +int pmemobj_tx_xpublish(struct pobj_action *actv, size_t actvcnt, uint64_t flags); (EXPERIMENTAL) +void pmemobj_cancel(PMEMobjpool *pop, struct pobj_action *actv, + size_t actvcnt); (EXPERIMENTAL) + +POBJ_RESERVE_NEW(pop, t, act) (EXPERIMENTAL) +POBJ_RESERVE_ALLOC(pop, t, size, act) (EXPERIMENTAL) +POBJ_XRESERVE_NEW(pop, t, act, flags) (EXPERIMENTAL) +POBJ_XRESERVE_ALLOC(pop, t, size, act, flags) (EXPERIMENTAL) +``` + +# DESCRIPTION # + +All of the functions described so far have an immediate effect on the persistent +state of the pool, and as such, the cost of maintaining fail-safety is paid +outright and, most importantly, in the calling thread. This behavior makes +implementing algorithms involving relaxed consistency guarantees difficult, if +not outright impossible. + +The following set of functions introduce a mechanism that allows one to delay +the persistent publication of a set of prepared actions to an arbitrary moment +in time of the execution of a program. + +The publication is fail-safe atomic in the scope of the entire collection of +actions. If a program exits without publishing the actions, or the actions are +canceled, any resources reserved by those actions are released and placed back in +the pool. + +A single action is represented by a single `struct pobj_action`. Functions that +create actions take that structure by pointer, whereas functions that publish +actions take array of actions and the size of the array. The actions can be +created, and published, from different threads. +When creating actions, the *act* argument must be non-NULL and point to a +`struct pobj_action`, the structure will be populated by the function and must +not be modified or deallocated until after publishing. + +The **pmemobj_reserve**() functions performs a transient reservation of an object. +Behaves similarly to **pmemobj_alloc**(3), but performs no modification to the +persistent state. +The object returned by this function can be freely modified without worrying +about fail-safe atomicity until the object has been published. Any modifications +of the object must be manually persisted, just like in the case of the atomic API. + +**pmemobj_xreserve**() is equivalent to **pmemobj_reserve**(), but with an +additional *flags* argument that is a bitmask of the following values: + ++ **POBJ_XALLOC_ZERO** - zero the allocated object (and persist it) + ++ **POBJ_CLASS_ID(class_id)** - allocate an object from the allocation class +*class_id*. The class id cannot be 0. + ++ **POBJ_ARENA_ID(arena_id)** - allocate an object from the arena specified by +*arena_id*. The arena must exist, otherwise, the behavior is undefined. +If *arena_id* is equal 0, then arena assigned to the current thread will be used. + +**pmemobj_defer_free**() function creates a deferred free action, meaning that +the provided object will be freed when the action is published. Calling this +function with a NULL OID is invalid and causes undefined behavior. + +The **pmemobj_set_value** function prepares an action that, once published, will +modify the memory location pointed to by *ptr* to *value*. + +The **pmemobj_publish** function publishes the provided set of actions. The +publication is fail-safe atomic. Once done, the persistent state will reflect +the changes contained in the actions. + +The **pmemobj_tx_publish** function moves the provided actions to the scope of +the transaction in which it is called. Only object reservations are supported +in transactional publish. Once done, the reserved objects will follow normal +transactional semantics. Can only be called during *TX_STAGE_WORK*. + +The **pmemobj_tx_xpublish**() function behaves exactly the same as +**pmemobj_tx_publish**() when *flags* equals zero. *flags* is a +bitmask of the following values: + ++ **POBJ_XPUBLISH_NO_ABORT** - if the function does not end successfully, +do not abort the transaction. + +The **pmemobj_cancel** function releases any resources held by the provided +set of actions and invalidates all actions. + +The **POBJ_RESERVE_NEW** macro is a typed variant of **pmemobj_reserve**. +The size of the reservation is determined from the provided type *t*. + +The **POBJ_RESERVE_ALLOC** macro is a typed variant of **pmemobj_reserve**. +The *size* of the reservation is user-provided. + +The **POBJ_XRESERVE_NEW** and the **POBJ_XRESERVE_ALLOC** macros are equivalent +to **POBJ_RESERVE_NEW** and the **POBJ_RESERVE_ALLOC**, but with an additional +*flags* argument defined for **pmemobj_xreserve**(). + +# EXAMPLES # + +The following code shows atomic append of two objects into a singly linked list. + +```c +struct list_node { + int value; + PMEMoid next; +}; +/* statically allocate the array of actions */ +struct pobj_action actv[4]; + +/* reserve, populate and persist the first object */ +PMEMoid tail = pmemobj_reserve(pop, &actv[0], sizeof(struct list_node), 0); +if (TOID_IS_NULL(tail)) + return -1; +D_RW(tail)->value = 1; +D_RW(tail)->next = OID_NULL; +pmemobj_persist(pop, D_RW(tail), sizeof(struct list_node)); + +/* reserve, populate and persist the second object */ +PMEMoid head = pmemobj_reserve(pop, &actv[1], sizeof(struct list_node), 0); +if (TOID_IS_NULL(head)) + return -1; +D_RW(head)->value = 2; +D_RW(head)->next = tail; +pmemobj_persist(pop, D_RW(head), sizeof(struct list_node)); + +/* create actions to set the PMEMoid to the new values */ +pmemobj_set_value(pop, &actv[2], &D_RO(root)->head.pool_uuid_lo, head.pool_uuid_lo); +pmemobj_set_value(pop, &actv[3], &D_RO(root)->head.off, head.off); + +/* atomically publish the above actions */ +pmemobj_publish(pop, actv, 4); +``` + +# RETURN VALUE # + +On success, **pmemobj_reserve**() functions return a handle to the newly +reserved object. Otherwise an *OID_NULL* is returned. + +On success, **pmemobj_tx_publish**() returns 0. Otherwise, +the transaction is aborted, the stage is changed to *TX_STAGE_ONABORT* +and *errno* is set appropriately. + +On success, **pmemobj_tx_xpublish**() returns 0. Otherwise, the error number +is returned, **errno** is set and when flags do not contain **POBJ_XPUBLISH_NO_ABORT**, +the transaction is aborted. + +On success, **pmemobj_publish**() returns 0. Otherwise, returns -1 and *errno* +is set appropriately. + +# SEE ALSO # + +**pmemobj_alloc**(3), **pmemobj_tx_alloc**(3), **libpmemobj**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_alloc.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_alloc.3.md new file mode 100644 index 0000000000..651368e046 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_alloc.3.md @@ -0,0 +1,280 @@ +--- +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_alloc.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2020, Intel Corporation) + +[comment]: <> (pmemobj_alloc.3 -- man page for non-transactional atomic allocations) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_alloc**(), **pmemobj_xalloc**(), **pmemobj_zalloc**(), +**pmemobj_realloc**(), **pmemobj_zrealloc**(), **pmemobj_strdup**(), +**pmemobj_wcsdup**(), **pmemobj_alloc_usable_size**(), **pmemobj_defrag**(), +**POBJ_NEW**(), **POBJ_ALLOC**(), **POBJ_ZNEW**(), **POBJ_ZALLOC**(), +**POBJ_REALLOC**(), **POBJ_ZREALLOC**(), **POBJ_FREE**() +- non-transactional atomic allocations + +# SYNOPSIS # + +```c +#include + +typedef int (*pmemobj_constr)(**PMEMobjpool *pop, void *ptr, void *arg); +int pmemobj_alloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size, + uint64_t type_num, pmemobj_constr constructor, void *arg); +int pmemobj_xalloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size, + uint64_t type_num, uint64_t flags, pmemobj_constr constructor, + void *arg); (EXPERIMENTAL) +int pmemobj_zalloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size, + uint64_t type_num); +void pmemobj_free(PMEMoid *oidp); +int pmemobj_realloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size, + uint64_t type_num); +int pmemobj_zrealloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size, + uint64_t type_num); +int pmemobj_strdup(PMEMobjpool *pop, PMEMoid *oidp, const char *s, + uint64_t type_num); +int pmemobj_wcsdup(PMEMobjpool *pop, PMEMoid *oidp, const wchar_t *s, + uint64_t type_num); +size_t pmemobj_alloc_usable_size(PMEMoid oid); +int pmemobj_defrag(PMEMobjpool *pop, PMEMoid **oidv, size_t oidcnt, + struct pobj_defrag_result *result); + +POBJ_NEW(PMEMobjpool *pop, TOID *oidp, TYPE, pmemobj_constr constructor, + void *arg) +POBJ_ALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size, + pmemobj_constr constructor, void *arg) +POBJ_ZNEW(PMEMobjpool *pop, TOID *oidp, TYPE) +POBJ_ZALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size) +POBJ_REALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size) +POBJ_ZREALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size) +POBJ_FREE(TOID *oidp) +``` + +# DESCRIPTION # + +Functions described in this document provide the mechanism to allocate, +resize and free objects from the persistent memory pool in a thread-safe +and fail-safe manner. All the routines are atomic with respect to other threads +and any power-fail interruptions. If any of these operations is torn by program +failure or system crash, on recovery they are guaranteed to be entirely completed +or discarded, leaving the persistent memory heap and internal object containers +in a consistent state. + +All these functions should be used outside transactions. If executed within +an open transaction they are considered durable immediately after completion. +Changes made with these functions will not be rolled back if the transaction +is aborted or interrupted. They have no information about other changes made +by transactional API, so if the same data is modified in a single transaction +using transactional and then non-transactional API, transaction abort +will likely corrupt the data. + +The allocations are always aligned to a cache-line boundary. + +The *pmemobj_constr* type represents a constructor for atomic allocation +from the persistent memory heap associated with memory pool *pop*. *ptr* +is a pointer to the allocated memory area and *arg* is a user-defined +argument passed to the constructor. + +The **pmemobj_alloc**() function allocates a new object from the persistent +memory heap associated with memory pool *pop*. The *PMEMoid* of the allocated +object is stored in *oidp*. If *oidp* is NULL, then the newly allocated object +may be accessed only by iterating objects in the object container associated +with the type number *type_num*, as described in **POBJ_FOREACH**(3). If *oidp* +points to a memory location from the **pmemobj** heap, *oidp* is modified +atomically. Before returning, **pmemobj_alloc**() calls the *constructor* +function, passing the pool handle *pop*, the pointer to the newly allocated +object in *ptr*, and the *arg* argument. It is guaranteed that the +allocated object is either properly initialized, or if the allocation +is interrupted before the constructor completes, the memory space reserved +for the object is reclaimed. *size* can be any non-zero value; however, +due to internal padding and object metadata, the actual size of the allocation +will differ from the requested size by at least 64 bytes. For this reason, +making allocations of a size less than 64 bytes is extremely inefficient +and discouraged. The allocated object is added to the internal container +associated with *type_num*. + +**pmemobj_xalloc**() is equivalent to **pmemobj_alloc**(), but with an +additional *flags* argument that is a bitmask of the following values: + ++ **POBJ_XALLOC_ZERO** - zero the allocated object (equivalent of **pmemobj_zalloc**()) + ++ **POBJ_CLASS_ID(class_id)** - allocate an object from the allocation class +*class_id*. The class id cannot be 0. + ++ **POBJ_ARENA_ID(arena_id)** - allocate an object from the arena specified by +*arena_id*. The arena must exist, otherwise, the behavior is undefined. +If *arena_id* is equal 0, then arena assigned to the current thread will be used. + +The **pmemobj_zalloc**() function allocates a new zeroed object from +the persistent memory heap associated with memory pool *pop*. The *PMEMoid* +of the allocated object is stored in *oidp*. If *oidp* is NULL, then +the newly allocated object may be accessed only by iterating objects in the +object container associated with the type number *type_num*, as described in +**POBJ_FOREACH**(3). If *oidp* points to a memory location from the **pmemobj** +heap, *oidp* is modified atomically. *size* can be any non-zero value; +however, due to internal padding and object metadata, the actual size +of the allocation will differ from the requested one by at least 64 bytes. +For this reason, making allocations of a size less than 64 bytes is extremely +inefficient and discouraged. The allocated object is added to the internal +container associated with *type_num*. + +The **pmemobj_free**() function frees the memory space represented by *oidp*, +which must have been allocated by a previous call to **pmemobj_alloc**(), +**pmemobj_xalloc**(), **pmemobj_zalloc**(), **pmemobj_realloc**(), or +**pmemobj_zrealloc**(). **pmemobj_free**() provides the same semantics as +**free**(3), but instead of operating on the process heap supplied by the +system, it operates on the persistent memory heap. If *oidp* is **OID_NULL**, +no operation is performed. If *oidp* is NULL or if it points to the root +object's *OID*, the behavior of **pmemobj_free**() is undefined. *oidp* is +set to **OID_NULL** after the memory is freed. If *oidp* points to a memory +location from the **pmemobj** heap, *oidp* is modified atomically. + +The **pmemobj_realloc**() function changes the size of the object represented +by *oidp* to *size* bytes. **pmemobj_realloc**() provides similar semantics to +**realloc**(3), but operates on the persistent memory heap associated with +memory pool *pop*. The resized object is also added or moved to the internal +container associated with type number *type_num*. The contents will be +unchanged in the range from the start of the region up to the minimum of the +old and new sizes. If the new size is larger than the old size, the added +memory will *not* be initialized. If *oidp* is *OID_NULL*, then the call is +equivalent to *pmemobj_alloc(pop, size, type_num)*. If *size* is equal to zero, +and *oidp* is not **OID_NULL**, then the call is equivalent to +*pmemobj_free(oid)*. Unless *oidp* is **OID_NULL**, it must have been allocated +by an earlier call to **pmemobj_alloc**(), **pmemobj_xalloc**(), +**pmemobj_zalloc**(), **pmemobj_realloc**(), or **pmemobj_zrealloc**(). Note +that the object handle value may change as a result of reallocation. If the +object was moved, the memory space represented by *oid* is reclaimed. If +*oidp* points to a memory location from the **pmemobj** heap, *oidp* is +modified atomically. If *oidp* is NULL or if it points to the root +object's *OID*, the behavior of **pmemobj_realloc**() is undefined. + +**pmemobj_zrealloc**() is equivalent to **pmemobj_realloc**(), except that +if the new size is larger than the old size, the added memory will be zeroed. + +The **pmemobj_strdup**() function stores a handle to a new object in *oidp* +which is a duplicate of the string *s*. **pmemobj_strdup**() provides the +same semantics as **strdup**(3), but operates on the persistent memory heap +associated with memory pool *pop*. If *oidp* is NULL, then the newly allocated +object may be accessed only by iterating objects in the object container +associated with type number *type_num*, as described in **POBJ_FOREACH**(3). +If *oidp* points to a memory location from the **pmemobj** heap, *oidp* +is modified atomically. The allocated string object is also added to the +internal container associated with type number *type_num*. Memory for the new +string is obtained with **pmemobj_alloc**(), on the given memory pool, and can +be freed with **pmemobj_free**() on the same memory pool. + +**pmemobj_wcsdup**() is equivalent to **pmemobj_strdup**(), but operates on +a wide character string (wchar_t) rather than a standard character string. + +The **pmemobj_alloc_usable_size**() function provides the same semantics as +**malloc_usable_size**(3), but instead of the process heap supplied by the +system, it operates on the persistent memory heap. + +The **POBJ_NEW**() macro is a wrapper around the **pmemobj_alloc**() function. +Instead of taking a pointer to *PMEMoid*, it takes a pointer to the typed *OID* +of type name *TYPE*, and passes the size and type number from the typed *OID* +to **pmemobj_alloc**(). + +The **POBJ_ALLOC**() macro is equivalent to **POBJ_NEW**, except that instead +of using the size of the typed *OID*, passes *size* to **pmemobj_alloc**(). + +The **POBJ_ZNEW**() macro is a wrapper around the **pmemobj_zalloc**() +function. Instead of taking a pointer to *PMEMoid*, it takes a pointer to the +typed *OID* of type name *TYPE*, and passes the size and type number from +the typed *OID* to **pmemobj_zalloc**(). + +The **POBJ_ZALLOC**() macro is equivalent to **POBJ_ZNEW**, except that instead +of using the size of the typed *OID*, passes *size* to **pmemobj_zalloc**(). + +The **POBJ_REALLOC**() macro is a wrapper around the **pmemobj_realloc**() +function. Instead of taking a pointer to *PMEMoid*, it takes a pointer to the +typed *OID* of type name *TYPE*, and passes the type number from the typed +*OID* to **pmemobj_realloc**(). + +The **POBJ_ZREALLOC**() macro is a wrapper around the **pmemobj_zrealloc**() +function. Instead of taking a pointer to *PMEMoid*, it takes a pointer to the +typed *OID* of type name *TYPE*, and passes the type number from the typed +*OID* to **pmemobj_zrealloc**(). + +The **POBJ_FREE**() macro is a wrapper around the **pmemobj_free**() function +which takes a pointer to the typed *OID* instead of to *PMEMoid*. + +The **pmemobj_defrag**() function performs defragmentation +on the objects provided through the array of pointers to PMEMoids *oidv* +with size *oidcnt*. If an object from the provided array is selected to be moved +to a new location in the heap, it is reallocated and all provided pointers +to that object are atomically updated. +To maintain data structure consistency, applications should always provide +all pointers for an object to **pmemobj_defrag** method. This ensures that, +even in the presence of failures, all pointers to the object will either point +to the old or a new location. +All objects and pointers to objects should belong to the pool *pop* or, +in case of pointers, can also reside in volatile memory. +Defragmentation across pools is not supported. +Objects in the array that are *OID_NULL* are skipped over and no operation +is performed on them. All other objects must have been allocated +by an earlier call to **pmemobj_alloc**(), **pmemobj_xalloc**(), +**pmemobj_zalloc**(), **pmemobj_realloc**(), **pmemobj_zrealloc**(), +**pmemobj_strdup**() or **pmemobj_wcsdup**(). +The *result* variable is an instance of *struct pobj_defrag_result* and, +if not NULL, can be used to read *total*, the number of objects found that +were processed, and *relocated*, the number of objects that were +relocated during defragmentation. These variables are always initialized and +can be non-zero, even if the return value of **pmemobj_defrag**() indicated a +failure. This is because the failure might have occurred after some objects were +already processed. + +# RETURN VALUE # + +On success, **pmemobj_alloc**() and **pmemobj_xalloc** return 0. If *oidp* +is not NULL, the *PMEMoid* of the newly allocated object is stored in *oidp*. +If the allocation fails, -1 is returned and *errno* is set appropriately. If +the constructor returns a non-zero value, the allocation is canceled, -1 is +returned, and *errno* is set to **ECANCELED**. If *size* equals 0, or the +*flags* for **pmemobj_xalloc** are invalid, -1 is returned, *errno* is set +to **EINVAL**, and *oidp* is left untouched. + +On success, **pmemobj_zalloc**() returns 0. If *oidp* is not NULL, the +*PMEMoid* of the newly allocated object is stored in *oidp*. If the allocation +fails, it returns -1 and sets *errno* appropriately. If *size* equals 0, it +returns -1, sets *errno* to **EINVAL**, and leaves *oidp* untouched. + +The **pmemobj_free**() function returns no value. + +On success, **pmemobj_realloc**() and **pmemobj_zrealloc**() return 0 and +update *oidp* if necessary. On error, they return -1 and set *errno* +appropriately. + +On success, **pmemobj_strdup**() and **pmemobj_wcsdup**() return 0. If +*oidp* is not NULL, the *PMEMoid* of the duplicated string object is stored +in *oidp*. If *s* is NULL, they return -1, set *errno* to **EINVAL**, and +leave *oidp* untouched. On other errors, they return -1 and set *errno* +appropriately. + +The **pmemobj_alloc_usable_size**() function returns the number of usable bytes +in the object represented by *oid*. If *oid* is **OID_NULL**, it returns 0. + +On success, **pmemobj_defrag**() returns 0. If defragmentation was +unsuccessful or only partially successful (i.e. if it was aborted halfway +through due to lack of resources), -1 is returned. + +# SEE ALSO # + +**free**(3), **POBJ_FOREACH**(3), **realloc**(3), +**strdup**(3), **wcsdup**(3), **libpmemobj**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_ctl_get.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_ctl_get.3.md new file mode 100644 index 0000000000..7f650ab7b7 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_ctl_get.3.md @@ -0,0 +1,421 @@ +--- +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_ctl_get.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2021, Intel Corporation) + +[comment]: <> (pmemobj_ctl_get.3 -- man page for libpmemobj CTL) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[CTL NAMESPACE](#ctl-namespace)
+[CTL EXTERNAL CONFIGURATION](#ctl-external-configuration)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_ctl_get**(), +**pmemobj_ctl_set**(), +**pmemobj_ctl_exec**() +- Query and modify libpmemobj internal behavior (EXPERIMENTAL) + +# SYNOPSIS # + +```c +#include + +int pmemobj_ctl_get(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL) +int pmemobj_ctl_set(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL) +int pmemobj_ctl_exec(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL) +``` + +# DESCRIPTION # + +The **pmemobj_ctl_get**(), **pmemobj_ctl_set**() and **pmemobj_ctl_exec**() +functions provide a uniform interface for querying and modifying the internal +behavior of **libpmemobj**(7) through the control (CTL) namespace. + +The *name* argument specifies an entry point as defined in the CTL namespace +specification. The entry point description specifies whether the extra *arg* is +required. Those two parameters together create a CTL query. The functions and +the entry points are thread-safe unless +indicated otherwise below. If there are special conditions for calling an entry +point, they are explicitly stated in its description. The functions propagate +the return value of the entry point. If either *name* or *arg* is invalid, -1 +is returned. + +If the provided ctl query is valid, the CTL functions will always return 0 +on success and -1 on failure, unless otherwise specified in the entry point +description. + +See more in **pmem_ctl**(5) man page. + +# CTL NAMESPACE # + +prefault.at_create | rw | global | int | int | - | boolean + +If set, every page of the pool will be touched and written to when the pool +is created, in order to trigger page allocation and minimize the performance +impact of pagefaults. Affects only the **pmemobj_create**() function. + +prefault.at_open | rw | global | int | int | - | boolean + +If set, every page of the pool will be touched and written to when the pool +is opened, in order to trigger page allocation and minimize the performance +impact of pagefaults. Affects only the **pmemobj_open**() function. + +sds.at_create | rw | global | int | int | - | boolean + +If set, force-enables or force-disables SDS feature during pool creation. +Affects only the **pmemobj_create**() function. See **pmempool_feature_query**(3) +for information about SDS (SHUTDOWN_STATE) feature. + +copy_on_write.at_open | rw | global | int | int | - | boolean + +If set, pool is mapped in such a way that modifications don't reach the +underlying medium. From the user's perspective this means that when the pool +is closed all changes are reverted. This feature is not supported for pools +located on Device DAX. + +tx.debug.skip_expensive_checks | rw | - | int | int | - | boolean + +Turns off some expensive checks performed by the transaction module in "debug" +builds. Ignored in "release" builds. + +tx.debug.verify_user_buffers | rw | - | int | int | - | boolean + +Enables verification of user buffers provided by +**pmemobj_tx_log_append_buffer**(3) API. For now the only verified aspect +is whether the same buffer is used simultaneously in 2 or more transactions +or more than once in the same transaction. This value should not be modified +at runtime if any transaction for the current pool is in progress. + +tx.cache.size | rw | - | long long | long long | - | integer + +Size in bytes of the transaction snapshot cache. In a larger cache the +frequency of persistent allocations is lower, but with higher fixed cost. + +This should be set to roughly the sum of sizes of the snapshotted regions in +an average transaction in the pool. + +This entry point is not thread safe and should not be modified if there are any +transactions currently running. + +This value must be a in a range between 0 and **PMEMOBJ_MAX_ALLOC_SIZE**, +otherwise this entry point will fail. + +tx.cache.threshold | rw | - | long long | long long | - | integer + +This entry point is deprecated. +All snapshots, regardless of the size, use the transactional cache. + +tx.post_commit.queue_depth | rw | - | int | int | - | integer + +This entry point is deprecated. + +tx.post_commit.worker | r- | - | void * | - | - | - + +This entry point is deprecated. + +tx.post_commit.stop | r- | - | void * | - | - | - + +This entry point is deprecated. + +heap.narenas.automatic | r- | - | unsigned | - | - | - + +Reads the number of arenas used in automatic scheduling of memory operations +for threads. By default, this value is equal to the number of available processors. +An arena is a memory management structure which enables concurrency by taking +exclusive ownership of parts of the heap and allowing associated threads to allocate +without contention. + +heap.narenas.total | r- | - | unsigned | - | - | - + +Reads the number of all created arenas. It includes automatic arenas +created by default and arenas created using heap.arena.create CTL. + +heap.narenas.max | rw- | - | unsigned | unsigned | - | - + +Reads or writes the maximum number of arenas that can be created. +This entry point is not thread-safe with regards to heap +operations (allocations, frees, reallocs). + +heap.arena.[arena_id].size | r- | - | uint64_t | - | - | - + +Reads the total amount of memory in bytes which is currently +exclusively owned by the arena. Large differences in this value between +arenas might indicate an uneven scheduling of memory resources. +The arena id cannot be 0. + +heap.thread.arena_id | rw- | - | unsigned | unsigned | - | - + +Reads the index of the arena assigned to the current thread or +assigns arena with specific id to the current thread. +The arena id cannot be 0. + +heap.arena.create | --x | - | - | - | unsigned | - + +Creates and initializes one new arena in the heap. +This entry point reads an id of the new created arena. + +Newly created arenas by this CTL are inactive, which means that +the arena will not be used in the automatic scheduling of +memory requests. To activate the new arena, use heap.arena.[arena_id].automatic CTL. + +Arena created using this CTL can be used for allocation by explicitly +specifying the *arena_id* for **POBJ_ARENA_ID(id)** flag in +**pmemobj_tx_xalloc**()/**pmemobj_xalloc**()/**pmemobj_xreserve()** functions. + +By default, the number of arenas is limited to 1024. + +heap.arena.[arena_id].automatic | rw- | - | boolean | boolean | - | - + +Reads or modifies the state of the arena. +If set, the arena is used in automatic scheduling of memory operations for threads. +This should be set to false if the application wants to manually manage allocator +scalability through explicitly assigning arenas to threads by using heap.thread.arena_id. +The arena id cannot be 0 and at least one automatic arena must exist. + +heap.arenas_assignment_type | rw | global | `enum pobj_arenas_assignment_type` | `enum pobj_arenas_assignment_type` | - | string + +Reads or modifies the behavior of arenas assignment for threads. By default, +each thread is assigned its own arena from the pool of automatic arenas +(described earlier). This consumes one TLS key from the OS for every open +pool. Applications that wish to avoid this behavior can instead rely on one +global arena assignment per pool. This might limits scalability if not using +arenas explicitly. + +The argument for this CTL is an enum with the following types: + + - **POBJ_ARENAS_ASSIGNMENT_THREAD_KEY**, string value: `thread`. + Default, threads use individually assigned arenas. + - **POBJ_ARENAS_ASSIGNMENT_GLOBAL**, string value: `global`. + Threads use one global arena. + +Changing this value has no impact on already open pools. It should typically be +set at the beginning of the application, before any pools are opened or created. + +heap.arenas_default_max | rw- | global | unsigned | unsigned | - | integer + +Reads or writes the number of arenas that are created by default on startup of +the heap's runtime state. +This value by default is equal to the number of online CPUs available on the +platform, but can be decreased or increased depending on application's +scalability requirements. + +heap.alloc_class.[class_id].desc | rw | - | `struct pobj_alloc_class_desc` | +`struct pobj_alloc_class_desc` | - | integer, integer, integer, string + +Describes an allocation class. Allows one to create or view the internal +data structures of the allocator. + +Creating custom allocation classes can be beneficial for both raw allocation +throughput, scalability and, most importantly, fragmentation. By carefully +constructing allocation classes that match the application workload, +one can entirely eliminate external and internal fragmentation. For example, +it is possible to easily construct a slab-like allocation mechanism for any +data structure. + +The `[class_id]` is an index field. Only values between 0-254 are valid. +If setting an allocation class, but the `class_id` is already taken, the +function will return -1. +The values between 0-127 are reserved for the default allocation classes of the +library and can be used only for reading. + +The recommended method for retrieving information about all allocation classes +is to call this entry point for all class ids between 0 and 254 and discard +those results for which the function returns an error. + +This entry point takes a complex argument. + +``` +struct pobj_alloc_class_desc { + size_t unit_size; + size_t alignment; + unsigned units_per_block; + enum pobj_header_type header_type; + unsigned class_id; +}; +``` + +The first field, `unit_size`, is an 8-byte unsigned integer that defines the +allocation class size. While theoretically limited only by +**PMEMOBJ_MAX_ALLOC_SIZE**, for most workloads this value should be between +8 bytes and 2 megabytes. + +The `alignment` field specifies the user data alignment of objects allocated +using the class. If set, must be a power of two and an even divisor of unit +size. Alignment is limited to maximum of 2 megabytes. +All objects have default alignment of 64 bytes, but the user data alignment +is affected by the size of the chosen header. + +The `units_per_block` field defines how many units a single block of memory +contains. This value will be adjusted to match the internal size of the +block (256 kilobytes or a multiple thereof). For example, given a class with +a `unit_size` of 512 bytes and a `units_per_block` of 1000, a single block of +memory for that class will have 512 kilobytes. +This is relevant because the bigger the block size, the less frequently blocks +need to be fetched, resulting in lower contention on global heap state. +If the CTL call is being done at runtime, the `units_per_block` variable of the +provided alloc class structure is modified to match the actual value. + +The `header_type` field defines the header of objects from the allocation class. +There are three types: + + - **POBJ_HEADER_LEGACY**, string value: `legacy`. Used for allocation classes + prior to version 1.3 of the library. Not recommended for use. + Incurs a 64 byte metadata overhead for every object. + Fully supports all features. + - **POBJ_HEADER_COMPACT**, string value: `compact`. Used as default for all + predefined allocation classes. + Incurs a 16 byte metadata overhead for every object. + Fully supports all features. + - **POBJ_HEADER_NONE**, string value: `none`. Header type that + incurs no metadata overhead beyond a single bitmap entry. Can be used + for very small allocation classes or when objects must be adjacent to + each other. + This header type does not support type numbers (type number is always + 0) or allocations that span more than one unit. + +The `class_id` field is an optional, runtime-only variable that allows the +user to retrieve the identifier of the class. This will be equivalent to the +provided `[class_id]`. This field cannot be set from a config file. + +The allocation classes are a runtime state of the library and must be created +after every open. It is highly recommended to use the configuration file to +store the classes. + +This structure is declared in the `libpmemobj/ctl.h` header file. Please refer +to this file for an in-depth explanation of the allocation classes and relevant +algorithms. + +Allocation classes constructed in this way can be leveraged by explicitly +specifying the class using **POBJ_CLASS_ID(id)** flag in **pmemobj_tx_xalloc**()/**pmemobj_xalloc**() +functions. + +Example of a valid alloc class query string: +``` +heap.alloc_class.128.desc=500,0,1000,compact +``` +This query, if executed, will create an allocation class with an id of 128 that +has a unit size of 500 bytes, has at least 1000 units per block and uses +a compact header. + +For reading, function returns 0 if successful, if the allocation class does +not exist it sets the errno to **ENOENT** and returns -1; + +This entry point can fail if any of the parameters of the allocation class +is invalid or if exactly the same class already exists. + +heap.alloc_class.new.desc | -w | - | - | `struct pobj_alloc_class_desc` | - | integer, integer, integer, string + +Same as `heap.alloc_class.[class_id].desc`, but instead of requiring the user +to provide the class_id, it automatically creates the allocation class with the +first available identifier. + +This should be used when it's impossible to guarantee unique allocation class +naming in the application (e.g. when writing a library that uses libpmemobj). + +The required class identifier will be stored in the `class_id` field of the +`struct pobj_alloc_class_desc`. + +stats.enabled | rw | - | enum pobj_stats_enabled | enum pobj_stats_enabled | - | +string + +Enables or disables runtime collection of statistics. There are two types of +statistics: persistent and transient ones. Persistent statistics survive pool +restarts, whereas transient ones don't. Statistics are not recalculated after +enabling; any operations that occur between disabling and re-enabling will not +be reflected in subsequent values. + +Only transient statistics are enabled by default. Enabling persistent statistics +may have non-trivial performance impact. + +stats.heap.curr_allocated | r- | - | uint64_t | - | - | - + +Reads the number of bytes currently allocated in the heap. If statistics were +disabled at any time in the lifetime of the heap, this value may be +inaccurate. + +This is a persistent statistic. + +stats.heap.run_allocated | r- | - | uint64_t | - | - | - + +Reads the number of bytes currently allocated using run-based allocation +classes, i.e., huge allocations are not accounted for in this statistic. +This is useful for comparison against stats.heap.run_active to estimate the +ratio between active and allocated memory. + +This is a transient statistic and is rebuilt every time the pool is opened. + +stats.heap.run_active | r- | - | uint64_t | - | - | - + +Reads the number of bytes currently occupied by all run memory blocks, including +both allocated and free space, i.e., this is all the all space that's not +occupied by huge allocations. + +This value is a sum of all allocated and free run memory. In systems where +memory is efficiently used, `run_active` should closely track +`run_allocated`, and the amount of active, but free, memory should be minimal. + +A large relative difference between active memory and allocated memory is +indicative of heap fragmentation. This information can be used to make +a decision to call **pmemobj_defrag()**(3) if the fragmentation looks to be high. + +However, for small heaps `run_active` might be disproportionately higher than +`run_allocated` because the allocator typically activates a significantly larger +amount of memory than is required to satisfy a single request in the +anticipation of future needs. For example, the first allocation of 100 bytes +in a heap will trigger activation of 256 kilobytes of space. + +This is a transient statistic and is rebuilt lazily every time the pool +is opened. + +heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long long + +Reads or modifies the granularity with which the heap grows when OOM. +Valid only if the poolset has been defined with directories. + +A granularity of 0 specifies that the pool will not grow automatically. + +This entry point can fail if the granularity value is non-zero and smaller +than *PMEMOBJ_MIN_PART*. + +heap.size.extend | --x | - | - | - | uint64_t | - + +Extends the heap by the given size. Must be larger than *PMEMOBJ_MIN_PART*. + +This entry point can fail if the pool does not support extend functionality or +if there's not enough space left on the device. + +debug.heap.alloc_pattern | rw | - | int | int | - | - + +Single byte pattern that is used to fill new uninitialized memory allocation. +If the value is negative, no pattern is written. This is intended for +debugging, and is disabled by default. + +# CTL EXTERNAL CONFIGURATION # + +In addition to direct function call, each write entry point can also be set +using two alternative methods. + +The first method is to load a configuration directly from the **PMEMOBJ_CONF** +environment variable. + +The second method of loading an external configuration is to set the +**PMEMOBJ_CONF_FILE** environment variable to point to a file that contains +a sequence of ctl queries. + +See more in **pmem_ctl**(5) man page. + +# SEE ALSO # + +**libpmemobj**(7), **pmem_ctl**(5) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_first.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_first.3.md new file mode 100644 index 0000000000..3a9813855a --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_first.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_first.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pmemobj_first.3 -- man page for pmemobj container operations) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_first**(), **pmemobj_next**(), +**POBJ_FIRST**(), **POBJ_FIRST_TYPE_NUM**(), +**POBJ_NEXT**(), **POBJ_NEXT_TYPE_NUM**(), +**POBJ_FOREACH**(), **POBJ_FOREACH_SAFE**(), +**POBJ_FOREACH_TYPE**(), **POBJ_FOREACH_SAFE_TYPE**() +- pmemobj container operations + +# SYNOPSIS # + +```c +#include + +PMEMoid pmemobj_first(PMEMobjpool *pop); +PMEMoid pmemobj_next(PMEMoid oid); + +POBJ_FIRST(PMEMobjpool *pop, TYPE) +POBJ_FIRST_TYPE_NUM(PMEMobjpool *pop, uint64_t type_num) +POBJ_NEXT(TOID oid) +POBJ_NEXT_TYPE_NUM(PMEMoid oid) + +POBJ_FOREACH(PMEMobjpool *pop, PMEMoid varoid) +POBJ_FOREACH_SAFE(PMEMobjpool *pop, PMEMoid varoid, PMEMoid nvaroid) +POBJ_FOREACH_TYPE(PMEMobjpool *pop, TOID var) +POBJ_FOREACH_SAFE_TYPE(PMEMobjpool *pop, TOID var, TOID nvar) +``` + +# DESCRIPTION # + +The **libpmemobj**(7) container operations provide a mechanism that allows +iteration through the internal object collection, either looking for a +specific object, or performing a specific operation on each object of a given +type. Software should not make any assumptions about the order of the objects +in the internal object containers. + +The **pmemobj_first**() function returns the first object from the pool. + +The **POBJ_FIRST**() macro returns the first object from the pool of +the type specified by *TYPE*. + +The **POBJ_FIRST_TYPE_NUM**() macro returns the first object from the pool +of the type specified by *type_num*. + +The **pmemobj_next**() function returns the next object from the pool. + +The **POBJ_NEXT**() macro returns the next object of the same type +as the object referenced by *oid*. + +The **POBJ_NEXT_TYPE_NUM**() macro returns the next object of the same type +number as the object referenced by *oid*. + +The following four macros provide a more convenient way to iterate through the +internal collections, performing a specific operation on each object. + +The **POBJ_FOREACH**() macro performs a specific operation on each allocated +object stored in the persistent memory pool *pop*. It traverses the internal +collection of all the objects, assigning a handle to each element in turn to +*varoid*. + +The **POBJ_FOREACH_TYPE**() macro performs a specific operation on each +allocated object stored in the persistent memory pool *pop* that has the same +type as *var*. It traverses the internal collection of all the objects of the +specified type, assigning a handle to each element in turn to *var*. + +The macros **POBJ_FOREACH_SAFE**() and **POBJ_FOREACH_SAFE_TYPE**() work in a +similar fashion as **POBJ_FOREACH**() and **POBJ_FOREACH_TYPE**(), except that +prior to performing the operation on the object, they preserve a handle to the +next object in the collection by assigning it to *nvaroid* or *nvar*, +respectively. This allows safe deletion of selected objects while iterating +through the collection. + +# RETURN VALUE # + +**pmemobj_first**() returns the first object from the pool, or, if the pool +is empty, **OID_NULL**. + +**pmemobj_next**() returns the next object from the pool. If the object +referenced by *oid* is the last object in the collection, or if *oid* +is *OID_NULL*, **pmemobj_next**() returns **OID_NULL**. + +# SEE ALSO # + +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_list_insert.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_list_insert.3.md new file mode 100644 index 0000000000..42602cf56a --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_list_insert.3.md @@ -0,0 +1,164 @@ +--- +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_list_insert.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pmemobj_list_insert.3 -- man page for non-transactional persistent atomic lists) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_list_insert**(), **pmemobj_list_insert_new**(), +**pmemobj_list_move**(), **pmemobj_list_remove**() +- non-transactional persistent atomic lists functions + +# SYNOPSIS # + +```c +#include + +int pmemobj_list_insert(PMEMobjpool *pop, size_t pe_offset, void *head, + PMEMoid dest, int before, PMEMoid oid); + +PMEMoid pmemobj_list_insert_new(PMEMobjpool *pop, size_t pe_offset, + void *head, PMEMoid dest, int before, size_t size, + uint64_t type_num, pmemobj_constr constructor, void arg); + +int pmemobj_list_move(PMEMobjpool *pop, + size_t pe_old_offset, void *head_old, + size_t pe_new_offset, void *head_new, + PMEMoid dest, int before, PMEMoid oid); + +int pmemobj_list_remove(PMEMobjpool *pop, size_t pe_offset, + void *head, PMEMoid oid, int free); +``` + +# DESCRIPTION # + +In addition to the container operations on internal object collections +described in **pmemobj_first**(3), **libpmemobj**(7) provides +a mechanism for organizing persistent objects in user-defined, persistent, +atomic, circular, doubly-linked lists. All the routines and macros operating +on the persistent lists provide atomicity with respect to any power-fail +interruptions. If any of those operations is torn by program failure or system +crash, on recovery they are guaranteed to be entirely completed or discarded, +leaving the lists, persistent memory heap and internal object containers in a +consistent state. + +The persistent atomic circular doubly linked lists support the following functionality: + ++ Insertion of an object at the head of the list, or at the end of the list. ++ Insertion of an object before or after any element in the list. ++ Atomic allocation and insertion of a new object at the head of the list, or at the end of the list. ++ Atomic allocation and insertion of a new object before or after any element in the list. ++ Atomic moving of an element from one list to the specific location on another list. ++ Removal of any object in the list. ++ Atomic removal and freeing of any object in the list. ++ Forward or backward traversal through the list. + +A list is headed by a *list_head* structure containing the object handle of the +first element on the list. The elements are doubly linked so that an arbitrary +element can be removed without the need to traverse the list. New elements can +be added to the list before or after an existing element, at the head of the +list, or at the tail of the list. A list may be traversed in either direction. + +The user-defined structure of each element must contain a field of type +*list_entry* that holds the object handles to the previous and next element +on the list. Both the *list_head* and the *list_entry* structures are +declared in **\**. + +The functions below are intended to be used outside transactions - transactional +variants are described in manpages to functions mentioned at **TRANSACTIONAL OBJECT +MANIPULATION** in **libpmemobj**(7). Note that operations performed using this +non-transactional API are independent from their transactional counterparts. +If any non-transactional allocations or list manipulations are performed within +an open transaction, the changes will not be rolled back if such a transaction +is aborted or interrupted. + +The list insertion and move functions use a common set of arguments to define +where an object will be inserted into the list. *dest* identifies the element +before or after which the object will be inserted, or, if *dest* is +**OID_NULL**, indicates that the object should be inserted at the head or +tail of the list. *before* determines where the object will be inserted: + ++ **POBJ_LIST_DEST_BEFORE** - insert the element before the existing +element *dest* + ++ **POBJ_LIST_DEST_AFTER** - insert the element after the existing element +*dest* + ++ **POBJ_LIST_DEST_HEAD** - when *dest* is **OID_NULL**, insert the element +at the head of the list + ++ **POBJ_LIST_DEST_TAIL** - when *dest* is **OID_NULL**, insert the element +at the tail of the list + +>NOTE: Earlier versions of **libpmemobj**(7) do not define +**POBJ_LIST_DEST_BEFORE** and **POBJ_LIST_DEST_AFTER**. Use 1 for before, +and 0 for after. + +The **pmemobj_list_insert**() function inserts the element represented by +object handle *oid* into the list referenced by *head*, at the location +specified by *dest* and *before* as described above. *pe_offset* +specifies the offset of the structure that connects the elements in +the list. All the handles *head*, *dest* and *oid* must point to objects +allocated from memory pool *pop*. *head* and *oid* cannot be **OID_NULL**. + +The **pmemobj_list_insert_new**() function atomically allocates a new object +of given *size* and type *type_num* and inserts it into the list referenced +by *head* at the location specified by *dest* and *before* as described +above. *pe_offset* specifies the offset of the structure that connects the +elements in the list. The handles *head* and *dest* must point to objects +allocated from memory pool *pop*. Before returning, +**pmemobj_list_insert_new**() calls the *constructor* function, passing the +pool handle *pop*, the pointer to the newly allocated object *ptr*, and the +*arg* argument. It is guaranteed that the allocated object is either properly +initialized or, if the allocation is interrupted before the constructor +completes, the memory space reserved for the object is reclaimed. *head* +cannot be **OID_NULL**. The allocated object is also added to the internal +container associated with *type_num*, as described in **POBJ_FOREACH**(3). + +The **pmemobj_list_move**() function moves the object represented by object +handle *oid* from the list referenced by *head_old* to the list referenced +by *head_new*, inserting it at the location specified by *dest* and *before* +as described above. *pe_old_offset* and *pe_new_offset* specify the offsets +of the structures that connect the elements in the old and new lists, +respectively. All the handles *head_old*, *head_new*, *dest* and *oid* must +point to objects allocated from memory pool *pop*. *head_old*, *head_new* +and *oid* cannot be **OID_NULL**. + +The **pmemobj_list_remove**() function removes the object represented by object +handle *oid* from the list referenced by *head*. If *free* is set, it also +removes the object from the internal object container and frees the associated +memory space. *pe_offset* specifies the offset of the structure that connects +the elements in the list. Both *head* and *oid* must point to objects allocated +from memory pool *pop* and cannot be **OID_NULL**. + +# RETURN VALUE # + +On success, **pmemobj_list_insert**(), **pmemobj_list_remove**() and +**pmemobj_list_move**() return 0. On error, they return -1 and set +*errno* appropriately. + +On success, **pmemobj_list_insert_new**() returns a handle to the newly +allocated object. If the constructor returns a non-zero value, the allocation +is canceled, -1 is returned, and *errno* is set to **ECANCELED**. +On other errors, **OID_NULL** is returned and *errno* is set appropriately. + +# SEE ALSO # + +**pmemobj_first**(3), **POBJ_FOREACH**(3), **libpmemobj**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_memcpy_persist.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_memcpy_persist.3.md new file mode 100644 index 0000000000..1c7b5301ea --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_memcpy_persist.3.md @@ -0,0 +1,186 @@ +--- +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_memcpy_persist.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pmemobj_memcpy_persist.3 -- man page for Low-level memory manipulation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[EXAMPLES](#examples)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_persist**(), **pmemobj_xpersist**(), **pmemobj_flush**(), +**pmemobj_xflush**(), **pmemobj_drain**(), **pmemobj_memcpy**(), +**pmemobj_memmove**(), **pmemobj_memset**(), **pmemobj_memcpy_persist**(), +**pmemobj_memset_persist**() - low-level memory manipulation functions + +# SYNOPSIS # + +```c +#include + +void pmemobj_persist(PMEMobjpool *pop, const void *addr, + size_t len); +void pmemobj_flush(PMEMobjpool *pop, const void *addr, + size_t len); +void pmemobj_drain(PMEMobjpool *pop); + +int pmemobj_xpersist(PMEMobjpool *pop, const void *addr, + size_t len, unsigned flags); +int pmemobj_xflush(PMEMobjpool *pop, const void *addr, + size_t len, unsigned flags); + +void *pmemobj_memcpy(PMEMobjpool *pop, void *dest, + const void *src, size_t len, unsigned flags); +void *pmemobj_memmove(PMEMobjpool *pop, void *dest, + const void *src, size_t len, unsigned flags); +void *pmemobj_memset(PMEMobjpool *pop, void *dest, + int c, size_t len, unsigned flags); + +void *pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest, + const void *src, size_t len); +void *pmemobj_memset_persist(PMEMobjpool *pop, void *dest, + int c, size_t len); +``` + +# DESCRIPTION # + +The **libpmemobj**-specific low-level memory manipulation functions described +here leverage the knowledge of the additional configuration options available +for **libpmemobj**(7) pools, such as replication. They also take advantage of +the type of storage behind the pool and use appropriate flush/drain functions. +It is advised to use these functions in conjunction with **libpmemobj**(7) +objects rather than using low-level memory manipulation functions from +**libpmem**. + +**pmemobj_persist**() forces any changes in the range \[*addr*, *addr*+*len*) +to be stored durably in persistent memory. Internally this may call either +**pmem_msync**(3) or **pmem_persist**(3). There are no alignment restrictions +on the range described by *addr* and *len*, but **pmemobj_persist**() may +expand the range as necessary to meet platform alignment requirements. + +>WARNING: +Like **msync**(2), there is nothing atomic or transactional about this call. +Any unwritten stores in the given range will be written, but some stores may +have already been written by virtue of normal cache eviction/replacement +policies. Correctly written code must not depend on stores waiting until +**pmemobj_persist**() is called to become persistent - they can become +persistent at any time before **pmemobj_persist**() is called. + +The **pmemobj_flush**() and **pmemobj_drain**() functions provide partial +versions of the **pmemobj_persist**() function described above. +These functions allow advanced programs to create their own variations of +**pmemobj_persist**(). +For example, a program that needs to flush several discontiguous ranges can +call **pmemobj_flush**() for each range and then follow up by calling +**pmemobj_drain**() once. For more information on partial flushing operations, +see **pmem_flush**(3). + +**pmemobj_xpersist**() is a version of **pmemobj_persist**() function with +additional *flags* argument. +It supports only the **PMEMOBJ_F_RELAXED** flag. +This flag indicates that memory transfer operation does +not require 8-byte atomicity guarantees. + +**pmemobj_xflush**() is a version of **pmemobj_flush**() function with +additional *flags* argument. +It supports only the **PMEMOBJ_F_RELAXED** flag. + +The **pmemobj_memmove**(), **pmemobj_memcpy**() and **pmemobj_memset**() functions +provide the same memory copying as their namesakes **memmove**(3), **memcpy**(3), +and **memset**(3), and ensure that the result has been flushed to persistence +before returning (unless **PMEMOBJ_MEM_NOFLUSH** flag was used). +Valid flags for those functions: + ++ **PMEMOBJ_F_RELAXED** - This flag indicates that memory transfer operation + does not require 8-byte atomicity guarantees. + ++ **PMEMOBJ_F_MEM_NOFLUSH** - Don't flush anything. + This implies **PMEMOBJ_F_MEM_NODRAIN**. + Using this flag only makes sense when it's followed by any function that + flushes data. + +The remaining flags say *how* the operation should be done, and are merely hints. + ++ **PMEMOBJ_F_MEM_NONTEMPORAL** - Use non-temporal instructions. + This flag is mutually exclusive with **PMEMOBJ_F_MEM_TEMPORAL**. + On x86\_64 this flag is mutually exclusive with **PMEMOBJ_F_MEM_NOFLUSH**. + ++ **PMEMOBJ_F_MEM_TEMPORAL** - Use temporal instructions. + This flag is mutually exclusive with **PMEMOBJ_F_MEM_NONTEMPORAL**. + ++ **PMEMOBJ_F_MEM_WC** - Use write combining mode. + This flag is mutually exclusive with **PMEMOBJ_F_MEM_WB**. + On x86\_64 this is an alias for **PMEMOBJ_F_MEM_NONTEMPORAL**. + On x86\_64 this flag is mutually exclusive with **PMEMOBJ_F_MEM_NOFLUSH**. + ++ **PMEMOBJ_F_MEM_WB** - Use write back mode. + This flag is mutually exclusive with **PMEMOBJ_F_MEM_WC**. + On x86\_64 this is an alias for **PMEMOBJ_F_MEM_TEMPORAL**. + +**pmemobj_memcpy_persist**() is an alias for **pmemobj_memcpy**() with flags equal to 0. + +**pmemobj_memset_persist**() is an alias for **pmemobj_memset**() with flags equal to 0. + +# RETURN VALUE # + +**pmemobj_memmove**(), **pmemobj_memcpy**(), **pmemobj_memset**(), +**pmemobj_memcpy_persist**() and **pmemobj_memset_persist**() return destination +buffer. + +**pmemobj_persist**(), **pmemobj_flush**() and **pmemobj_drain**() +do not return any value. + +**pmemobj_xpersist**() and **pmemobj_xflush**() returns non-zero value and +sets errno to EINVAL only if not supported flags has been provided. + +# EXAMPLES # + +The following code is functionally equivalent to +**pmemobj_memcpy_persist**(): + +```c +void * +pmemobj_memcpy_persist(PMEMobjpool *pop, void *dest, + const void *src, size_t len) +{ + void *retval = memcpy(dest, src, len); + + pmemobj_persist(pop, dest, len); + + return retval; +} +``` + +**pmemobj_persist**() can be thought of as this: + +```c +void +pmemobj_persist(PMEMobjpool *pop, const void *addr, size_t len) +{ + /* flush the processor caches */ + pmemobj_flush(pop, addr, len); + + /* wait for any pmem stores to drain from HW buffers */ + pmemobj_drain(pop); +} +``` + +# SEE ALSO # + +**memcpy**(3), **memset**(3), **pmem_msync**(3), +**pmem_persist**(3), **libpmem**(7) **libpmemobj**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_mutex_zero.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_mutex_zero.3.md new file mode 100644 index 0000000000..600d48c571 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_mutex_zero.3.md @@ -0,0 +1,195 @@ +--- +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_mutex_zero.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pmemobj_mutex_zero.3 -- man page for locking functions from libpmemobj library) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_mutex_zero**(), **pmemobj_mutex_lock**(), **pmemobj_mutex_timedlock**(), +**pmemobj_mutex_trylock**(), **pmemobj_mutex_unlock**(), + +**pmemobj_rwlock_zero**(), **pmemobj_rwlock_rdlock**(), **pmemobj_rwlock_wrlock**(), +**pmemobj_rwlock_timedrdlock**(), **pmemobj_rwlock_timedwrlock**(), **pmemobj_rwlock_tryrdlock**(), +**pmemobj_rwlock_trywrlock**(), **pmemobj_rwlock_unlock**(), + +**pmemobj_cond_zero**(), **pmemobj_cond_broadcast**(), **pmemobj_cond_signal**(), +**pmemobj_cond_timedwait**(), **pmemobj_cond_wait**() +- pmemobj synchronization primitives + +# SYNOPSIS # + +```c +#include + +void pmemobj_mutex_zero(PMEMobjpool *pop, PMEMmutex *mutexp); +int pmemobj_mutex_lock(PMEMobjpool *pop, PMEMmutex *mutexp); +int pmemobj_mutex_timedlock(PMEMobjpool *pop, PMEMmutex *restrict mutexp, + const struct timespec *restrict abs_timeout); +int pmemobj_mutex_trylock(PMEMobjpool *pop, PMEMmutex *mutexp); +int pmemobj_mutex_unlock(PMEMobjpool *pop, PMEMmutex *mutexp); + +void pmemobj_rwlock_zero(PMEMobjpool *pop, PMEMrwlock *rwlockp); +int pmemobj_rwlock_rdlock(PMEMobjpool *pop, PMEMrwlock *rwlockp); +int pmemobj_rwlock_wrlock(PMEMobjpool *pop, PMEMrwlock *rwlockp); +int pmemobj_rwlock_timedrdlock(PMEMobjpool *pop, PMEMrwlock *restrict rwlockp, + const struct timespec *restrict abs_timeout); +int pmemobj_rwlock_timedwrlock(PMEMobjpool *pop, PMEMrwlock *restrict rwlockp, + const struct timespec *restrict abs_timeout); +int pmemobj_rwlock_tryrdlock(PMEMobjpool *pop, PMEMrwlock *rwlockp); +int pmemobj_rwlock_trywrlock(PMEMobjpool *pop, PMEMrwlock *rwlockp); +int pmemobj_rwlock_unlock(PMEMobjpool *pop, PMEMrwlock *rwlockp); + +void pmemobj_cond_zero(PMEMobjpool *pop, PMEMcond *condp); +int pmemobj_cond_broadcast(PMEMobjpool *pop, PMEMcond *condp); +int pmemobj_cond_signal(PMEMobjpool *pop, PMEMcond *condp); +int pmemobj_cond_timedwait(PMEMobjpool *pop, PMEMcond *restrict condp, + PMEMmutex *restrict mutexp, const struct timespec *restrict abs_timeout); +int pmemobj_cond_wait(PMEMobjpool *pop, PMEMcond *restrict condp, + PMEMmutex *restrict mutexp); +``` + +# DESCRIPTION # + +**libpmemobj**(7) provides several types of synchronization primitives +designed to be used with persistent memory. The pmem-aware lock implementation +is based on the standard POSIX Threads Library, as described in +**pthread_mutex_init**(3), **pthread_rwlock_init**(3) and +**pthread_cond_init**(3). Pmem-aware locks provide semantics similar to +standard **pthread** locks, except that they are embedded in pmem-resident +objects and are considered initialized by zeroing them. Therefore, locks +allocated with **pmemobj_zalloc**(3) or **pmemobj_tx_zalloc**(3) do not require +another initialization step. For performance reasons, they are also padded up +to 64 bytes (cache line size). + +The fundamental property of pmem-aware locks is their automatic +reinitialization every time the persistent object store pool is opened. Thus, +all the pmem-aware locks may be considered initialized (unlocked) immediately +after the pool is opened, regardless of their state at the time the pool was +closed for the last time. + +Pmem-aware mutexes, read/write locks and condition variables must be declared +with the *PMEMmutex*, *PMEMrwlock*, or *PMEMcond* type, respectively. + +The **pmemobj_mutex_zero**() function explicitly initializes the pmem-aware +mutex *mutexp* by zeroing it. Initialization is not necessary if the object +containing the mutex has been allocated using **pmemobj_zalloc**(3) or +**pmemobj_tx_zalloc**(3). + +The **pmemobj_mutex_lock**() function locks the pmem-aware mutex *mutexp*. +If the mutex is already locked, the calling thread will block until the mutex +becomes available. If this is the first use of the mutex since the opening of +the pool *pop*, the mutex is automatically reinitialized and then locked. + +**pmemobj_mutex_timedlock**() performs the same action as +**pmemobj_mutex_lock**(), but will not wait beyond *abs_timeout* to obtain the +lock before returning. + +The **pmemobj_mutex_trylock**() function locks pmem-aware mutex *mutexp*. +If the mutex is already locked, **pthread_mutex_trylock**() will not block +waiting for the mutex, but will return an error. If this is the first +use of the mutex since the opening of the pool *pop*, the mutex is +automatically reinitialized and then locked. + +The **pmemobj_mutex_unlock**() function unlocks the pmem-aware mutex +*mutexp*. Undefined behavior follows if a thread tries to unlock a +mutex that has not been locked by it, or if a thread tries to release a mutex +that is already unlocked or has not been initialized. + +The **pmemobj_rwlock_zero**() function is used to explicitly initialize the +pmem-aware read/write lock *rwlockp* by zeroing it. Initialization is not +necessary if the object containing the lock has been allocated using +**pmemobj_zalloc**(3) or **pmemobj_tx_zalloc**(3). + +The **pmemobj_rwlock_rdlock**() function acquires a read lock on *rwlockp*, +provided that the lock is not presently held for writing and no writer threads +are presently blocked on the lock. If the read lock cannot be acquired +immediately, the calling thread blocks until it can acquire the lock. If this +is the first use of the lock since the opening of the pool *pop*, the lock is +automatically reinitialized and then acquired. + +**pmemobj_rwlock_timedrdlock**() performs the same action as +**pmemobj_rwlock_rdlock**(), but will not wait beyond *abs_timeout* to obtain +the lock before returning. A thread may hold multiple concurrent read locks. +If so, **pmemobj_rwlock_unlock**() must be called once for each lock obtained. +The results of acquiring a read lock while the calling thread holds a write +lock are undefined. + +The **pmemobj_rwlock_wrlock**() function blocks until a write lock can be +acquired against read/write lock *rwlockp*. If this is the first use of the +lock since the opening of the pool *pop*, the lock is automatically +reinitialized and then acquired. + +**pmemobj_rwlock_timedwrlock**() performs the same action, but will not wait +beyond *abs_timeout* to obtain the lock before returning. + +The **pmemobj_rwlock_tryrdlock**() function performs the same action as +**pmemobj_rwlock_rdlock**(), but does not block if the lock cannot be +immediately obtained. The results are undefined if the calling thread already +holds the lock at the time the call is made. + +The **pmemobj_rwlock_trywrlock**() function performs the same action as +**pmemobj_rwlock_wrlock**(), but does not block if the lock cannot be immediately +obtained. The results are undefined if the calling thread already holds the lock +at the time the call is made. + +The **pmemobj_rwlock_unlock**() function is used to release the read/write +lock previously obtained by **pmemobj_rwlock_rdlock**(), +**pmemobj_rwlock_wrlock**(), **pthread_rwlock_tryrdlock**(), or +**pmemobj_rwlock_trywrlock**(). + +The **pmemobj_cond_zero**() function explicitly initializes the pmem-aware +condition variable *condp* by zeroing it. Initialization is not necessary if +the object containing the condition variable has been allocated using +**pmemobj_zalloc**(3) or **pmemobj_tx_zalloc**(3). + +The difference between **pmemobj_cond_broadcast**() and +**pmemobj_cond_signal**() is that the former unblocks all threads waiting +for the condition variable, whereas the latter blocks only one waiting thread. +If no threads are waiting on *condp*, neither function has any effect. If more +than one thread is blocked on a condition variable, the used scheduling policy +determines the order in which threads are unblocked. The same mutex used for +waiting must be held while calling either function. Although neither function +strictly enforces this requirement, undefined behavior may follow if the mutex +is not held. + +The **pmemobj_cond_timedwait**() and **pmemobj_cond_wait**() functions block +on a condition variable. They must be called with mutex *mutexp* locked by +the calling thread, or undefined behavior results. These functions atomically +release mutex *mutexp* and cause the calling thread to block on the condition +variable *condp*; atomically here means "atomically with respect to access by +another thread to the mutex and then the condition variable". That is, if +another thread is able to acquire the mutex after the about-to-block thread +has released it, then a subsequent call to **pmemobj_cond_broadcast**() or +**pmemobj_cond_signal**() in that thread will behave as if it were issued +after the about-to-block thread has blocked. Upon successful return, the mutex +will be locked and owned by the calling thread. + +# RETURN VALUE # + +The **pmemobj_mutex_zero**(), **pmemobj_rwlock_zero**() +and **pmemobj_cond_zero**() functions return no value. + +Other locking functions return 0 on success. Otherwise, an error +number will be returned to indicate the error. + +# SEE ALSO # + +**pmemobj_tx_zalloc**(3), **pmemobj_zalloc**(3), **pthread_cond_init**(3), +**pthread_mutex_init**(3), **pthread_rwlock_init**(3), **libpmem**(7), +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_open.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_open.3.md new file mode 100644 index 0000000000..31ffaf8a1b --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_open.3.md @@ -0,0 +1,169 @@ +--- +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_open.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2023, Intel Corporation) + +[comment]: <> (pmemobj_open.3 -- man page for most commonly used functions from libpmemobj library) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[CAVEATS](#caveats)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_open**(), **pmemobj_create**(), +**pmemobj_close**(), **pmemobj_check**(), +**pmemobj_set_user_data**(), **pmemobj_get_user_data**() +- create, open, close and validate persistent memory transactional object store + +# SYNOPSIS # + +```c +#include + +PMEMobjpool *pmemobj_open(const char *path, const char *layout); +PMEMobjpool *pmemobj_create(const char *path, const char *layout, + size_t poolsize, mode_t mode); +void pmemobj_close(PMEMobjpool *pop); +int pmemobj_check(const char *path, const char *layout); + +void pmemobj_set_user_data(PMEMobjpool *pop, void *data); +void *pmemobj_get_user_data(PMEMobjpool *pop); +``` + +# DESCRIPTION # + +To use the pmem-resident transactional object store provided by +**libpmemobj**(7), a *memory pool* must first be created +with the **pmemobj_create**() function described below. Existing pools +may be opened with the **pmemobj_open**() function. + +As of **libpmemobj** **1.11**, these functions are thread-safe; be careful +if you have to use earlier versions of the library. + +Once created, the memory pool is represented by an opaque handle, +of type *PMEMobjpool\**, which is passed to most of the other **libpmemobj**(7) +functions. Internally, **libpmemobj**(7) will use either **pmem_persist**(3) +or **msync**(2) when it needs to flush changes, depending on whether the memory +pool appears to be persistent memory or a regular file (see the +**pmem_is_pmem**(3) function in **libpmem**(7) for more information). There is +no need for applications to flush changes directly when using the object +memory API provided by **libpmemobj**(7). + +The **pmemobj_create**() function creates a transactional object store with the +given total *poolsize*. *path* specifies the name of the memory pool file to be +created. *layout* specifies the application's layout type in the form of a +string. The layout name is not interpreted by **libpmemobj**(7), but may be +used as a check when **pmemobj_open**() is called. The layout name, including +the terminating null byte ('\0'), cannot be longer than **PMEMOBJ_MAX_LAYOUT** +as defined in **\**. A NULL *layout* is equivalent +to using an empty string as a layout name. *mode* specifies the permissions to +use when creating the file, as described by **creat**(2). The memory pool file +is fully allocated to the size *poolsize* using **posix_fallocate**(3). The +caller may choose to take responsibility for creating the memory pool file +by creating it before calling **pmemobj_create**(), and then specifying +*poolsize* as zero. In this case **pmemobj_create**() will take the pool size +from the size of the existing file and will verify that the file appears to be +empty by searching for any non-zero data in the pool header at the beginning of +the file. The minimum net pool size allowed by the library for a local +transactional object store is defined in **\** as +**PMEMOBJ_MIN_POOL**. + +Depending on the configuration of the system, the available non-volatile +memory space may be divided into multiple memory devices. +In such case, the maximum size of the pmemobj memory pool +could be limited by the capacity of a single memory device. +**libpmemobj**(7) allows building persistent memory +resident object store spanning multiple memory devices by creation of +persistent memory pools consisting of multiple files, where each part of +such a *pool set* may be stored on a different memory device +or pmem-aware filesystem. + +Creation of all the parts of the pool set can be done with **pmemobj_create**(); +however, the recommended method for creating pool sets is with the +**pmempool**(1) utility. + +When creating a pool set consisting of multiple files, the *path* argument +passed to **pmemobj_create**() must point to the special *set* file that defines +the pool layout and the location of all the parts of the pool set. The +*poolsize* argument must be 0. The meaning of the *layout* and *mode* arguments +does not change, except that the same *mode* is used for creation of all the +parts of the pool set. + +The *set* file is a plain text file, the structure of which is described in +**poolset**(5). + +The **pmemobj_open**() function opens an existing object store memory pool. +Similar to **pmemobj_create**(), *path* must identify either an existing +obj memory pool file, or the *set* file used to create a pool set. +If *layout* is non-NULL, it is compared to the layout +name provided to **pmemobj_create**() when the pool was first created. This can +be used to verify that the layout of the pool matches what was expected. +The application must have permission to open the file and memory map it with +read/write permissions. + +Be aware that if the pool contains bad blocks inside, opening can be aborted +by the SIGBUS signal, because currently the pool is not checked against +bad blocks during opening. It can be turned on by setting the CHECK_BAD_BLOCKS +compat feature. For details see description of this feature +in **pmempool-feature**(1). + +The **pmemobj_close**() function closes the memory pool indicated by *pop* and +deletes the memory pool handle. The object store itself lives on in the file +that contains it and may be re-opened at a later time using +**pmemobj_open**() as described above. + +The **pmemobj_check**() function performs a consistency check of the file +indicated by *path*. **pmemobj_check**() opens the given *path* read-only so +it never makes any changes to the file. This function is not supported on +Device DAX. + +The **pmemobj_set_user_data**() function associates custom volatile state, +represented by pointer *data*, with the given pool *pop*. This state can later +be retrieved using **pmemobj_get_user_data**() function. This state does not +survive pool close. If **pmemobj_set_user_data**() was not called for a given +pool, **pmemobj_get_user_data**() will return NULL. + +# RETURN VALUE # + +The **pmemobj_create**() function returns a memory pool handle to be used with +most of the functions in **libpmemobj**(7). On error it returns NULL +and sets *errno* appropriately. + +The **pmemobj_open**() function returns a memory pool handle to be used with +most of the functions in **libpmemobj**(7). If an error prevents the pool +from being opened, or if the given *layout* does not match the pool's layout, +**pmemobj_open**() returns NULL and sets *errno* appropriately. + +The **pmemobj_close**() function returns no value. + +The **pmemobj_check**() function returns 1 if the memory pool is found to be +consistent. Any inconsistencies found will cause **pmemobj_check**() to +return 0, in which case the use of the file with **libpmemobj**(7) will result +in undefined behavior. The debug version of **libpmemobj**(7) will provide +additional details on inconsistencies when **PMEMOBJ_LOG_LEVEL** is at least 1, +as described in the **DEBUGGING AND ERROR HANDLING** section in +**libpmemobj**(7). **pmemobj_check**() returns -1 and sets *errno* if it cannot +perform the consistency check due to other errors. + +# CAVEATS # + +Not all file systems support **posix_fallocate**(3). **pmemobj_create**() will +fail if the underlying file system does not support **posix_fallocate**(3). + +# SEE ALSO # + +**creat**(2), **msync**(2), **pmem_is_pmem**(3), **pmem_persist**(3), +**posix_fallocate**(3), **libpmem**(7), **libpmemobj**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_root.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_root.3.md new file mode 100644 index 0000000000..d40e14c236 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_root.3.md @@ -0,0 +1,98 @@ +--- +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_root.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pmemobj_root.3 -- man page for root object management) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_root**(), **pmemobj_root_construct**() +**POBJ_ROOT**(), **pmemobj_root_size**() - root object management + +# SYNOPSIS # + +```c +#include + +PMEMoid pmemobj_root(PMEMobjpool *pop, size_t size); +PMEMoid pmemobj_root_construct(PMEMobjpool *pop, size_t size, + pmemobj_constr constructor, void *arg); +POBJ_ROOT(PMEMobjpool *pop, TYPE) +size_t pmemobj_root_size(PMEMobjpool *pop); +``` + +# DESCRIPTION # + +The root object of a persistent memory pool is an entry point for all other +persistent objects allocated using the **libpmemobj** API. In other words, +every object stored in the persistent memory pool has the root +object at the end of its reference path. It may be assumed that for each +persistent memory pool the root object always exists, and there is exactly +one root object in each pool. + +The **pmemobj_root**() function creates or resizes the root object for the +persistent memory pool *pop*. If this is the first call to **pmemobj_root**(), +the requested *size* is greater than zero and the root object does not exist, +it is implicitly allocated +in a thread-safe manner, so the function may be called by more than one +thread simultaneously (as long as all threads use the identical *size* value). +The size of the root object is guaranteed to be not less than the requested +*size*. If the requested size is larger than the current size, the root +object is automatically resized. In such case, the old data is preserved and +the extra space is zeroed. If the requested size is equal to or smaller than +the current size, the root object remains unchanged. +If the requested *size* is equal to zero, the root object is not allocated. + +**pmemobj_root_construct**() performs the same actions as **pmemobj_root**(), +but instead of zeroing the newly allocated object a *constructor* function +is called to initialize the object. The constructor is also called on +reallocations. + +The **POBJ_ROOT**() macro works the same way as the **pmemobj_root**() function +except it returns a typed *OID* value. + +The **pmemobj_root_size**() function returns the current size of the root object +associated with the persistent memory pool *pop*. + +# RETURN VALUE # + +Upon success, **pmemobj_root**() returns a handle to the root object associated +with the persistent memory pool *pop*. The same root object handle is returned +in all the threads. If the requested object size is larger than the maximum +allocation size supported for the pool, or if there is not enough free +space in the pool to satisfy a reallocation request, **pmemobj_root**() returns +**OID_NULL** and sets *errno* to ENOMEM. +If the *size* was equal to zero and the root object has not been allocated, +**pmemobj_root**() returns **OID_NULL** and sets *errno* to EINVAL. + +If the **pmemobj_root_construct**() constructor fails, the allocation is +canceled, **pmemobj_root_construct**() returns *OID_NULL*, and *errno* is set +to **ECANCELED**. **pmemobj_root_size**() can be used in the constructor to +check whether this is the first call to the constructor. + +**POBJ_ROOT**() returns a typed *OID* of type *TYPE* instead of the +*PMEMoid* returned by **pmemobj_root**(). + +The **pmemobj_root_size**() function returns the current size of the root object +associated with the persistent memory pool *pop*. The returned size is the +largest value requested by any of the earlier **pmemobj_root**() calls. If the +root object has not been allocated yet, **pmemobj_root_size**() returns 0. + +# SEE ALSO # + +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_add_range.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_add_range.3.md new file mode 100644 index 0000000000..748bd94852 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_add_range.3.md @@ -0,0 +1,194 @@ +--- +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_tx_add_range.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2019, Intel Corporation) + +[comment]: <> (pmemobj_tx_add_range.3 -- man page for transactional object manipulation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_tx_add_range**(), **pmemobj_tx_add_range_direct**(), +**pmemobj_tx_xadd_range**(), **pmemobj_tx_xadd_range_direct**() + +**TX_ADD**(), **TX_ADD_FIELD**(), +**TX_ADD_DIRECT**(), **TX_ADD_FIELD_DIRECT**(), + +**TX_XADD**(), **TX_XADD_FIELD**(), +**TX_XADD_DIRECT**(), **TX_XADD_FIELD_DIRECT**(), + +**TX_SET**(), **TX_SET_DIRECT**(), +**TX_MEMCPY**(), **TX_MEMSET**() +- transactional object manipulation + +# SYNOPSIS # + +```c +#include + +int pmemobj_tx_add_range(PMEMoid oid, uint64_t off, size_t size); +int pmemobj_tx_add_range_direct(const void *ptr, size_t size); +int pmemobj_tx_xadd_range(PMEMoid oid, uint64_t off, size_t size, uint64_t flags); +int pmemobj_tx_xadd_range_direct(const void *ptr, size_t size, uint64_t flags); + +TX_ADD(TOID o) +TX_ADD_FIELD(TOID o, FIELD) +TX_ADD_DIRECT(TYPE *p) +TX_ADD_FIELD_DIRECT(TYPE *p, FIELD) + +TX_XADD(TOID o, uint64_t flags) +TX_XADD_FIELD(TOID o, FIELD, uint64_t flags) +TX_XADD_DIRECT(TYPE *p, uint64_t flags) +TX_XADD_FIELD_DIRECT(TYPE *p, FIELD, uint64_t flags) + +TX_SET(TOID o, FIELD, VALUE) +TX_SET_DIRECT(TYPE *p, FIELD, VALUE) +TX_MEMCPY(void *dest, const void *src, size_t num) +TX_MEMSET(void *dest, int c, size_t num) +``` + +# DESCRIPTION # + +**pmemobj_tx_add_range**() takes a "snapshot" of the memory block of given +*size*, located at given offset *off* in the object specified by *oid*, and +saves it to the undo log. The application is then free to directly modify the +object in that memory range. In case of a failure or abort, all the changes +within this range will be rolled back. The supplied block of memory has to be +within the pool registered in the transaction. This function must be called +during **TX_STAGE_WORK**. + +The **pmemobj_tx_xadd_range**() function behaves exactly the same as +**pmemobj_tx_add_range**() when *flags* equals zero. +*flags* is a bitmask of the following values: + ++ **POBJ_XADD_NO_FLUSH** - skip flush on commit (when application deals +with flushing or uses pmemobj_memcpy_persist) + ++ **POBJ_XADD_NO_SNAPSHOT** - added range will not be "snapshotted", i.e. any +changes made within it during the transaction will not be rolled backed after +abort + ++ **POBJ_XADD_ASSUME_INITIALIZED** - added range is assumed to be initialized. +If this flag is not specified, passing uninitialized memory will result in an +error when run under Valgrind memcheck. + ++ **POBJ_XADD_NO_ABORT** - if the function does not end successfully, +do not abort the transaction. + +**pmemobj_tx_add_range_direct**() behaves the same as +**pmemobj_tx_add_range**() with the exception that it operates on virtual +memory addresses and not persistent memory objects. It takes a "snapshot" of +a persistent memory block of given *size*, located at the given address *ptr* +in the virtual memory space and saves it to the undo log. The application is +then free to directly modify the object in that memory range. In case of a +failure or abort, all the changes within this range will be rolled back. +The supplied block of memory has to be within the pool registered in the +transaction. This function must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_xadd_range_direct**() function behaves exactly the same as +**pmemobj_tx_add_range_direct**() when *flags* equals zero. *flags* is a +bitmask of the following values: + ++ **POBJ_XADD_NO_FLUSH** - skip flush on commit (when application deals +with flushing or uses pmemobj_memcpy_persist) + ++ **POBJ_XADD_NO_SNAPSHOT** - added range will not be "snapshotted", i.e. any +changes made within it during the transaction will not be rolled backed after +abort + ++ **POBJ_XADD_ASSUME_INITIALIZED** - added range is assumed to be initialized. +If this flag is not specified, passing uninitialized memory will result in an +error when run under Valgrind memcheck. + ++ **POBJ_XADD_NO_ABORT** - if the function does not end successfully, +do not abort the transaction. + +Similarly to the macros controlling the transaction flow, **libpmemobj** +defines a set of macros that simplify the transactional operations on +persistent objects. Note that those macros operate on typed object handles, +thus eliminating the need to specify the size of the object, or the size and +offset of the field in the user-defined structure that is to be modified. + +The **TX_ADD_FIELD**() macro saves the current value of given *FIELD* of the +object referenced by a handle *o* in the undo log. The application is then free +to directly modify the specified *FIELD*. In case of a failure or abort, the +saved value will be restored. + +The **TX_XADD_FIELD**() macro works exactly like **TX_ADD_FIELD** when *flags* +equals 0. The *flags* argument is a bitmask of values described in +**pmemobj_tx_xadd_range**, above. + +The **TX_ADD**() macro takes a "snapshot" of the entire object referenced by +object handle *o* and saves it in the undo log. The object size is determined +from its *TYPE*. The application is then free to directly modify the object. +In case of a failure or abort, all the changes within the object will be +rolled back. + +The **TX_XADD**() macro works exactly like **TX_ADD** when *flags* equals 0. +The *flags* argument is a bitmask of values as described in +**pmemobj_tx_xadd_range**, above. + +The **TX_ADD_FIELD_DIRECT**() macro saves the current value of the given +*FIELD* of the object referenced by (direct) pointer *p* in the undo log. +The application is then free to directly modify the specified *FIELD*. In case +of a failure or abort, the saved value will be restored. + +The **TX_XADD_FIELD_DIRECT**() macro works exactly like **TX_ADD_FIELD_DIRECT** +when *flags* equals 0. The *flags* argument is a bitmask of values as described +in **pmemobj_tx_xadd_range_direct**, above. + +The **TX_ADD_DIRECT**() macro takes a "snapshot" of the entire object +referenced by (direct) pointer *p* and saves it in the undo log. The object +size is determined from its *TYPE*. The application is then free to directly +modify the object. In case of a failure or abort, all the changes within the +object will be rolled back. + +The **TX_XADD_DIRECT**() macro works exactly like **TX_ADD_DIRECT** when +*flags* equals 0. The *flags* argument is a bitmask of values as described in +**pmemobj_tx_xadd_range_direct**, above. + +The **TX_SET**() macro saves the current value of the given *FIELD* of the +object referenced by handle *o* in the undo log, and then sets its new *VALUE*. +In case of a failure or abort, the saved value will be restored. + +The **TX_SET_DIRECT**() macro saves in the undo log the current value of given +*FIELD* of the object referenced by (direct) pointer *p*, and then set its new +*VALUE*. In case of a failure or abort, the saved value will be restored. + +The **TX_MEMCPY**() macro saves in the undo log the current content of *dest* +buffer and then overwrites the first *num* bytes of its memory area with +the data copied from the buffer pointed by *src*. In case of a failure or abort, +the saved value will be restored. + +The **TX_MEMSET**() macro saves the current content of the *dest* buffer in the +undo log and then fills the first *num* bytes of its memory area with the +constant byte *c*. In case of a failure or abort, the saved value will be +restored. + +# RETURN VALUE # + +On success, **pmemobj_tx_add_range**() and **pmemobj_tx_add_range_direct**() +return 0. Otherwise, the stage is changed to **TX_STAGE_ONABORT**, +**errno** is set appropriately and transaction is aborted. + +On success, **pmemobj_tx_xadd_range**() and **pmemobj_tx_xadd_range_direct**() +returns 0. Otherwise, the error number is returned, **errno** is set and +when flags do not contain **POBJ_XADD_NO_ABORT**, the transaction is aborted. + +# SEE ALSO # + +**pmemobj_tx_alloc**(3), **pmemobj_tx_begin**(3), +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_alloc.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_alloc.3.md new file mode 100644 index 0000000000..0ec8074a71 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_alloc.3.md @@ -0,0 +1,260 @@ +--- +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_tx_alloc.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2019, Intel Corporation) + +[comment]: <> (pmemobj_tx_alloc.3 -- man page for transactional object manipulation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_tx_alloc**(), **pmemobj_tx_zalloc**(), +**pmemobj_tx_xalloc**(), **pmemobj_tx_realloc**(), +**pmemobj_tx_zrealloc**(), **pmemobj_tx_strdup**(), +**pmemobj_tx_xstrdup**(), **pmemobj_tx_wcsdup**(), +**pmemobj_tx_xwcsdup**(), **pmemobj_tx_free**(), +**pmemobj_tx_xfree**() + +**TX_NEW**(), **TX_ALLOC**(), +**TX_ZNEW**(), **TX_ZALLOC**(), +**TX_XALLOC**(), **TX_REALLOC**(), +**TX_ZREALLOC**(), **TX_STRDUP**(), +**TX_XSTRDUP**(), **TX_WCSDUP**(), +**TX_XWCSDUP**(), **TX_FREE**(), +**TX_XFREE**() +- transactional object manipulation + +# SYNOPSIS # + +```c +#include + +PMEMoid pmemobj_tx_alloc(size_t size, uint64_t type_num); +PMEMoid pmemobj_tx_zalloc(size_t size, uint64_t type_num); +PMEMoid pmemobj_tx_xalloc(size_t size, uint64_t type_num, uint64_t flags); +PMEMoid pmemobj_tx_realloc(PMEMoid oid, size_t size, uint64_t type_num); +PMEMoid pmemobj_tx_zrealloc(PMEMoid oid, size_t size, uint64_t type_num); +PMEMoid pmemobj_tx_strdup(const char *s, uint64_t type_num); +PMEMoid pmemobj_tx_wcsdup(const wchar_t *s, uint64_t type_num); +int pmemobj_tx_free(PMEMoid oid); +int pmemobj_tx_xfree(PMEMoid oid, uint64_t flags); + +TX_NEW(TYPE) +TX_ALLOC(TYPE, size_t size) +TX_ZNEW(TYPE) +TX_ZALLOC(TYPE, size_t size) +TX_XALLOC(TYPE, size_t size, uint64_t flags) +TX_REALLOC(TOID o, size_t size) +TX_ZREALLOC(TOID o, size_t size) +TX_STRDUP(const char *s, uint64_t type_num) +TX_WCSDUP(const wchar_t *s, uint64_t type_num) +TX_FREE(TOID o) +TX_XFREE(TOID o, uint64_t flags) +``` + +# DESCRIPTION # + +The **pmemobj_tx_alloc**() function transactionally allocates a new object of +given *size* and *type_num*. In contrast to the non-transactional allocations, +the objects are added to the internal object containers of given *type_num* +only after the transaction is committed, making the objects visible to the +**POBJ_FOREACH_\***() macros. This function must be called during +**TX_STAGE_WORK**. + +The **pmemobj_tx_zalloc**() function transactionally allocates a new zeroed +object of given *size* and *type_num*. This function must be called during +**TX_STAGE_WORK**. + +The **pmemobj_tx_xalloc**() function transactionally allocates a new object +of given *size* and *type_num*. The *flags* argument is a bitmask of the +following values: + ++ **POBJ_XALLOC_ZERO** - zero the allocated object (equivalent of pmemobj_tx_zalloc) + ++ **POBJ_XALLOC_NO_FLUSH** - skip flush on commit +(when application deals with flushing or uses pmemobj_memcpy_persist) + ++ **POBJ_CLASS_ID(class_id)** - allocate an object from the allocation +class with id equal to *class_id* + ++ **POBJ_ARENA_ID(arena_id)** - allocate an object from the arena specified by +*arena_id*. The arena must exist, otherwise, the behavior is undefined. +If *arena_id* is equal 0, then arena assigned to the current thread will be used. + ++ **POBJ_XALLOC_NO_ABORT** - if the function does not end successfully, +do not abort the transaction. + +This function must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_realloc**() function transactionally resizes an existing +object to the given *size* and changes its type to *type_num*. If *oid* is +**OID_NULL**, then the call is equivalent to *pmemobj_tx_alloc(pop, size, +type_num)*. If *size* is equal to zero and *oid* is not **OID_NULL**, then +the call is equivalent to *pmemobj_tx_free(oid)*. If the new size is larger +than the old size, the added memory will *not* be initialized. This function +must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_zrealloc**() function transactionally resizes an existing +object to the given *size* and changes its type to *type_num*. If the new +size is larger than the old size, the extended new space is zeroed. This +function must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_strdup**() function transactionally allocates a new object +containing a duplicate of the string *s* and assigns it a type *type_num*. +This function must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_xstrdup**() function behaves exactly the same as +**pmemobj_tx_strdup**() when *flags* equals zero. +The *flags* argument is a bitmask of values described in **pmemobj_tx_xalloc** section. + +The **pmemobj_tx_wcsdup**() function transactionally allocates a new object +containing a duplicate of the wide character string *s* and assigns it a type +*type_num*. This function must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_xwcsdup**() function behaves exactly the same as +**pmemobj_tx_wcsdup**() when *flags* equals zero. +The *flags* argument is a bitmask of values described in **pmemobj_tx_xalloc** section. + +The **pmemobj_tx_free**() function transactionally frees an existing object +referenced by *oid*. This function must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_xfree**() function behaves exactly the same as +**pmemobj_tx_free**() when *flags* equals zero. +*flags* is a bitmask of the following value: + ++ **POBJ_XFREE_NO_ABORT** - if the function does not end successfully, +do not abort the transaction. + +This function must be called during **TX_STAGE_WORK**. + +The **TX_NEW**() macro transactionally allocates a new object of given *TYPE* +and assigns it a type number read from the typed *OID*. The allocation size is +determined from the size of the user-defined structure *TYPE*. If successful +and called during **TX_STAGE_WORK** it returns a handle to the newly allocated +object. Otherwise, the stage is changed to **TX_STAGE_ONABORT**, **OID_NULL** +is returned, and *errno* is set appropriately. + +The **TX_ALLOC**() macro transactionally allocates a new object of given *TYPE* +and assigns it a type number read from the typed *OID*. The allocation size is +passed by *size* parameter. If successful and called during **TX_STAGE_WORK** +it returns a handle to the newly allocated object. Otherwise, the stage is set +to **TX_STAGE_ONABORT**, **OID_NULL** is returned, and *errno* is set +appropriately. + +The **TX_ZNEW**() macro transactionally allocates a new zeroed object of given +*TYPE* and assigns it a type number read from the typed *OID*. The allocation +size is determined from the size of the user-defined structure *TYPE*. If +successful and called during **TX_STAGE_WORK** it returns a handle to the newly +allocated object. Otherwise, stage changes to **TX_STAGE_ONABORT**, **OID_NULL** +is returned, and *errno* is set appropriately. + +The **TX_ZALLOC**() macro transactionally allocates a new zeroed object of +given *TYPE* and assigns it a type number read from the typed *OID*. The +allocation size is passed by *size* argument. If successful and called during +**TX_STAGE_WORK** it returns a handle to the newly allocated object. Otherwise, +the stage is changed to **TX_STAGE_ONABORT**, **OID_NULL** is returned, and +*errno* is set appropriately. + +The **TX_XALLOC**() macro transactionally allocates a new object of given +*TYPE* and assigns it a type number read from the typed *OID*. The allocation +size is passed by *size* argument. The *flags* argument is a bitmask of values +described in **pmemobj_tx_xalloc** section. If successful and called during +**TX_STAGE_WORK** it returns a handle to the newly allocated object. Otherwise, +the **OID_NULL** is returned, **errno** is set and when flags do not +contain **POBJ_XALLOC_NO_ABORT**, the transaction is aborted. + +The **TX_REALLOC**() macro transactionally resizes an existing object +referenced by a handle *o* to the given *size*. If successful and called during +**TX_STAGE_WORK** it returns a handle to the reallocated object. Otherwise, the +stage is changed to **TX_STAGE_ONABORT**, **OID_NULL** is returned, and *errno* +is set appropriately. + +The **TX_ZREALLOC**() macro transactionally resizes an existing object +referenced by a handle *o* to the given *size*. If the new size is larger than +the old size, the extended new space is zeroed. If successful and called during +**TX_STAGE_WORK** it returns a handle to the reallocated object. Otherwise, the +stage is changed to **TX_STAGE_ONABORT**, **OID_NULL** is returned, and *errno* +is set appropriately. + +The **TX_STRDUP**() macro transactionally allocates a new object containing a +duplicate of the string *s* and assigns it type *type_num*. If successful +and called during **TX_STAGE_WORK** it returns a handle to the newly allocated +object. Otherwise, the stage is changed to **TX_STAGE_ONABORT**, **OID_NULL** +is returned, and *errno* is set appropriately. + +The **TX_XSTRDUP**() macro transactionally allocates a new object containing a +duplicate of the string *s* and assigns it type *type_num*. The *flags* argument +is a bitmask of values described in **pmemobj_tx_xalloc** section. If successful and +called during **TX_STAGE_WORK** it returns a handle to the newly allocated +object. Otherwise, the **OID_NULL** is returned, **errno** is set and when flags +do not contain **POBJ_XALLOC_NO_ABORT**, the transaction is aborted. + +The **TX_WCSDUP**() macro transactionally allocates a new object containing a +duplicate of the wide character string *s* and assigns it a type *type_num*. If +successful and called during **TX_STAGE_WORK**, it returns a handle to the +newly allocated object. Otherwise, the stage is changed to **TX_STAGE_ONABORT**, +**OID_NULL** is returned, and *errno* is set appropriately. + +The **TX_XWCSDUP**() macro transactionally allocates a new object containing a +duplicate of the wide character string *s* and assigns it a type *type_num*. +The *flags* argument is a bitmask of values described in **pmemobj_tx_xalloc** section. +If successful and called during **TX_STAGE_WORK** it returns a handle to the +newly allocated object. Otherwise, the **OID_NULL** is returned, **errno** is set +and when flags do not contain **POBJ_XALLOC_NO_ABORT**, the transaction is aborted. + +The **TX_FREE**() macro transactionally frees the memory space represented by +an object handle *o*. If *o* is **OID_NULL**, no operation is performed. If +successful and called during **TX_STAGE_WORK**, **TX_FREE**() returns 0. +Otherwise, the stage is changed to **TX_STAGE_ONABORT** and *errno* is set appropriately. + +The **TX_XFREE**() macro transactionally frees the memory space represented by +an object handle *o*. If *o* is **OID_NULL**, no operation is performed. +The *flags* argument is a bitmask of values described in **pmemobj_tx_xfree** +section. If successful and called during **TX_STAGE_WORK**, **TX_FREE**() +returns 0. Otherwise, the error number is returned, **errno** is set and when +flags do not contain **POBJ_XFREE_NO_ABORT**, the transaction is aborted. + +# RETURN VALUE # + +On success, the **pmemobj_tx_alloc**(), **pmemobj_tx_zalloc**(), +**pmemobj_tx_strdup**() and **pmemobj_tx_wcsdup**() +functions return a handle to the newly allocated object. Otherwise, the stage +is changed to **TX_STAGE_ONABORT**, **OID_NULL** is returned, and *errno* is +set appropriately. If *size* equals 0, **OID_NULL** is returned and *errno* is +set appropriately. + +On success, the **pmemobj_tx_xalloc**(), **pmemobj_tx_xstrdup**() and +**pmemobj_tx_xwcsdup**() functions return a handle to the newly allocated object. +Otherwise, the **OID_NULL** is returned, **errno** is set and when flags do not +contain **POBJ_XALLOC_NO_ABORT**, the transaction is aborted. + +On success, **pmemobj_tx_realloc**() and **pmemobj_tx_zrealloc**() return +a handle to the resized object. Otherwise, the stage is changed to +**TX_STAGE_ONABORT**, **OID_NULL** is returned, and *errno* is set +appropriately. Note that the object handle value may change as a result of +reallocation. + +On success, **pmemobj_tx_free**() returns 0. Otherwise, the stage is changed +to **TX_STAGE_ONABORT**, **errno** is set appropriately and transaction is aborted + +On success **pmemobj_tx_xfree**() returns 0. Otherwise, the error number is +returned, **errno** is set and when flags do not contain **POBJ_XFREE_NO_ABORT**, +the transaction is aborted. + +# SEE ALSO # + +**pmemobj_tx_add_range**(3), **pmemobj_tx_begin**(3), +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_begin.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_begin.3.md new file mode 100644 index 0000000000..04d30a5b1d --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pmemobj_tx_begin.3.md @@ -0,0 +1,548 @@ +--- +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_tx_begin.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2020, Intel Corporation) + +[comment]: <> (pmemobj_tx_begin.3 -- man page for transactional object manipulation) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[CAVEATS](#caveats)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmemobj_tx_stage**(), + +**pmemobj_tx_begin**(), **pmemobj_tx_lock**(), +**pmemobj_tx_xlock**(), **pmemobj_tx_abort**(), +**pmemobj_tx_commit**(), **pmemobj_tx_end**(), +**pmemobj_tx_errno**(), **pmemobj_tx_process**(), + +**TX_BEGIN_PARAM**(), **TX_BEGIN_CB**(), +**TX_BEGIN**(), **TX_ONABORT**, +**TX_ONCOMMIT**, **TX_FINALLY**, **TX_END**, + +**pmemobj_tx_log_append_buffer**(), **pmemobj_tx_xlog_append_buffer**(), +**pmemobj_tx_log_auto_alloc**(), **pmemobj_tx_log_snapshots_max_size**(), +**pmemobj_tx_log_intents_max_size**(), + +**pmemobj_tx_set_user_data**(), +**pmemobj_tx_get_user_data**(), + +**pmemobj_tx_set_failure_behavior**(), +**pmemobj_tx_get_failure_behavior**() +- transactional object manipulation + +# SYNOPSIS # + +```c +#include + +enum pobj_tx_stage pmemobj_tx_stage(void); + +int pmemobj_tx_begin(PMEMobjpool *pop, jmp_buf *env, enum pobj_tx_param, ...); +int pmemobj_tx_lock(enum tx_lock lock_type, void *lockp); +int pmemobj_tx_xlock(enum tx_lock lock_type, void *lockp, uint64_t flags); +void pmemobj_tx_abort(int errnum); +void pmemobj_tx_commit(void); +int pmemobj_tx_end(void); +int pmemobj_tx_errno(void); +void pmemobj_tx_process(void); + +TX_BEGIN_PARAM(PMEMobjpool *pop, ...) +TX_BEGIN_CB(PMEMobjpool *pop, cb, arg, ...) +TX_BEGIN(PMEMobjpool *pop) +TX_ONABORT +TX_ONCOMMIT +TX_FINALLY +TX_END + +int pmemobj_tx_log_append_buffer(enum pobj_log_type type, void *addr, size_t size); +int pmemobj_tx_xlog_append_buffer(enum pobj_log_type type, void *addr, size_t size, uint64_t flags); +int pmemobj_tx_log_auto_alloc(enum pobj_log_type type, int on_off); +size_t pmemobj_tx_log_snapshots_max_size(size_t *sizes, size_t nsizes); +size_t pmemobj_tx_log_intents_max_size(size_t nintents); + +void pmemobj_tx_set_user_data(void *data); +void *pmemobj_tx_get_user_data(void); + +void pmemobj_tx_set_failure_behavior(enum pobj_tx_failure_behavior behavior); +enum pobj_tx_failure_behavior pmemobj_tx_get_failure_behavior(void); +``` + +# DESCRIPTION # + +The non-transactional functions and macros described in **pmemobj_alloc**(3), +**pmemobj_list_insert**(3) and **POBJ_LIST_HEAD**(3) only guarantee the +atomicity of a single operation on an object. In case of more complex changes +involving multiple operations on an object, or allocation and modification +of multiple objects, data consistency and fail-safety may be provided only +by using *atomic transactions*. + +A transaction is defined as series of operations on persistent memory +objects that either all occur, or nothing occurs. In particular, +if the execution of a transaction is interrupted by a power failure +or a system crash, it is guaranteed that after system restart, +all the changes made as a part of the uncompleted transaction +will be rolled back, restoring the consistent state of the memory +pool from the moment when the transaction was started. + +Note that transactions do not provide atomicity with respect +to other threads. All the modifications performed within the transactions +are immediately visible to other threads. Therefore it is the responsibility +of the application to implement a proper thread synchronization mechanism. + +Each thread may have only one transaction open at a time, but that +transaction may be nested. Nested transactions are flattened. Committing +the nested transaction does not commit the outer transaction; however, errors +in the nested transaction are propagated up to the outermost level, resulting +in the interruption of the entire transaction. + +Each transaction is visible only for the thread that started it. +No other threads can add operations, commit or abort the transaction +initiated by another thread. Multiple threads may have transactions open on a +given memory pool at the same time. + +Please see the **CAVEATS** section below for known limitations of the +transactional API. + +The **pmemobj_tx_stage**() function returns the current *transaction stage* +for a thread. Stages are changed only by the **pmemobj_tx_\***() functions. +Transaction stages are defined as follows: + ++ **TX_STAGE_NONE** - no open transaction in this thread + ++ **TX_STAGE_WORK** - transaction in progress + ++ **TX_STAGE_ONCOMMIT** - successfully committed + ++ **TX_STAGE_ONABORT** - starting the transaction failed or transaction aborted + ++ **TX_STAGE_FINALLY** - ready for clean up + +The **pmemobj_tx_begin**() function starts a new transaction in the current +thread. If called within an open transaction, it starts a nested transaction. +The caller may use the *env* argument to provide a pointer to a +calling environment to be restored in case of transaction abort. This +information must be provided by the caller using the **setjmp**(3) macro. + +A new transaction may be started only if the current stage is **TX_STAGE_NONE** +or **TX_STAGE_WORK**. If successful, the *transaction stage* changes to +**TX_STAGE_WORK**. Otherwise, the stage is changed to **TX_STAGE_ONABORT**. + +Optionally, a list of parameters for the transaction may be provided. +Each parameter consists of a type followed by a type-specific number +of values. Currently there are 4 types: + ++ **TX_PARAM_NONE**, used as a termination marker. No following value. + ++ **TX_PARAM_MUTEX**, followed by one value, a pmem-resident PMEMmutex + ++ **TX_PARAM_RWLOCK**, followed by one value, a pmem-resident PMEMrwlock + ++ **TX_PARAM_CB**, followed by two values: a callback function +of type *pmemobj_tx_callback*, and a void pointer + +Using **TX_PARAM_MUTEX** or **TX_PARAM_RWLOCK** causes the specified lock to +be acquired at the beginning of the transaction. **TX_PARAM_RWLOCK** acquires +the lock for writing. It is guaranteed that **pmemobj_tx_begin**() will acquire +all locks prior to successful completion, and they will be held by the current +thread until the outermost transaction is finished. Locks are taken in order +from left to right. To avoid deadlocks, the user is responsible for proper +lock ordering. + +**TX_PARAM_CB** registers the specified callback function to be executed at +each transaction stage. For **TX_STAGE_WORK**, the callback is executed prior +to commit. For all other stages, the callback is executed as the first +operation after a stage change. It will also be called after each transaction; +in this case the *stage* parameter will be set to **TX_STAGE_NONE**. +*pmemobj_tx_callback* must be compatible with: + +``` +void func(PMEMobjpool *pop, enum pobj_tx_stage stage, void *arg) +``` + +*pop* is a pool identifier used in **pmemobj_tx_begin**(), *stage* is a current +transaction stage and *arg* is the second parameter of **TX_PARAM_CB**. +Without considering transaction nesting, this mechanism can be considered an +alternative method for executing code between stages (instead of +**TX_ONCOMMIT**, **TX_ONABORT**, etc). However, there are 2 significant +differences when nested transactions are used: + ++ The registered function is executed only in the outermost transaction, +even if registered in an inner transaction. + ++ There can be only one callback in the entire transaction, that is, the +callback cannot be changed in an inner transaction. + +Note that **TX_PARAM_CB** does not replace the **TX_ONCOMMIT**, **TX_ONABORT**, +etc. macros. They can be used together: the callback will be executed *before* +a **TX_ONCOMMIT**, **TX_ONABORT**, etc. section. + +**TX_PARAM_CB** can be used when the code dealing with transaction stage +changes is shared between multiple users or when it must be executed only +in the outer transaction. For example it can be very useful when the +application must synchronize persistent and transient state. + +The **pmemobj_tx_lock**() function acquires the lock *lockp* of type +*lock_type* and adds it to the current transaction. *lock_type* may be +**TX_LOCK_MUTEX** or **TX_LOCK_RWLOCK**; *lockp* must be of type +*PMEMmutex* or *PMEMrwlock*, respectively. If *lock_type* is **TX_LOCK_RWLOCK** +the lock is acquired for writing. If the lock is not successfully +acquired, the function returns an error number. This function must be +called during **TX_STAGE_WORK**. + +The **pmemobj_tx_xlock**() function behaves exactly the same as +**pmemobj_tx_lock**() when *flags* equals **POBJ_XLOCK_NO_ABORT**. +When *flags* equals 0 and if the lock is not successfully +acquired,the transaction is aborted. +*flags* is a bitmask of the following values: + ++ **POBJ_XLOCK_NO_ABORT** - if the function does not end successfully, +do not abort the transaction. + +**pmemobj_tx_abort**() aborts the current transaction and causes a transition +to **TX_STAGE_ONABORT**. If *errnum* is equal to 0, the transaction +error code is set to **ECANCELED**; otherwise, it is set to *errnum*. +This function must be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_commit**() function commits the current open transaction and +causes a transition to **TX_STAGE_ONCOMMIT**. If called in the context of the +outermost transaction, all the changes may be considered as durably written +upon successful completion. This function must be called during +**TX_STAGE_WORK**. + +The **pmemobj_tx_end**() function performs a cleanup of the current +transaction. If called in the context of the outermost transaction, it releases +all the locks acquired by **pmemobj_tx_begin**() for outer and nested +transactions. If called in the context of a nested transaction, it returns +to the context of the outer transaction in **TX_STAGE_WORK**, without releasing +any locks. The **pmemobj_tx_end**() function can be called during +**TX_STAGE_NONE** if transitioned to this stage using **pmemobj_tx_process**(). +If not already in **TX_STAGE_NONE**, it causes the transition to +**TX_STAGE_NONE**. **pmemobj_tx_end** must always be called for each +**pmemobj_tx_begin**(), even if starting the transaction failed. This function +must *not* be called during **TX_STAGE_WORK**. + +The **pmemobj_tx_errno**() function returns the error code of the last transaction. + +The **pmemobj_tx_process**() function performs the actions associated with the +current stage of the transaction, and makes the transition to the next stage. +It must be called in a transaction. The current stage must always be obtained +by a call to **pmemobj_tx_stage**(). **pmemobj_tx_process**() performs +the following transitions in the transaction stage flow: + ++ **TX_STAGE_WORK** -> **TX_STAGE_ONCOMMIT** + ++ **TX_STAGE_ONABORT** -> **TX_STAGE_FINALLY** + ++ **TX_STAGE_ONCOMMIT** -> **TX_STAGE_FINALLY** + ++ **TX_STAGE_FINALLY** -> **TX_STAGE_NONE** + ++ **TX_STAGE_NONE** -> **TX_STAGE_NONE** + +**pmemobj_tx_process**() must not be called after calling **pmemobj_tx_end**() +for the outermost transaction. + +In addition to the above API, **libpmemobj**(7) offers a more intuitive method +of building transactions using the set of macros described below. When using +these macros, the complete transaction flow looks like this: + +```c +TX_BEGIN(Pop) { + /* the actual transaction code goes here... */ +} TX_ONCOMMIT { + /* + * optional - executed only if the above block + * successfully completes + */ +} TX_ONABORT { + /* + * optional - executed only if starting the transaction fails, + * or if transaction is aborted by an error or a call to + * pmemobj_tx_abort() + */ +} TX_FINALLY { + /* + * optional - if exists, it is executed after + * TX_ONCOMMIT or TX_ONABORT block + */ +} TX_END /* mandatory */ +``` + +```c +TX_BEGIN_PARAM(PMEMobjpool *pop, ...) +TX_BEGIN_CB(PMEMobjpool *pop, cb, arg, ...) +TX_BEGIN(PMEMobjpool *pop) +``` + +The **TX_BEGIN_PARAM**(), **TX_BEGIN_CB**() and **TX_BEGIN**() macros start +a new transaction in the same way as **pmemobj_tx_begin**(), except that instead +of the environment buffer provided by a caller, they set up the local *jmp_buf* +buffer and use it to catch the transaction abort. The **TX_BEGIN**() macro +starts a transaction without any options. **TX_BEGIN_PARAM** may be used when +there is a need to acquire locks prior to starting a transaction (such as +for a multi-threaded program) or set up a transaction stage callback. +**TX_BEGIN_CB** is just a wrapper around **TX_BEGIN_PARAM** that validates +the callback signature. (For compatibility there is also a **TX_BEGIN_LOCK** +macro, which is an alias for **TX_BEGIN_PARAM**). Each of these macros must be +followed by a block of code with all the operations that are to be performed +atomically. + +The **TX_ONABORT** macro starts a block of code that will be executed only +if starting the transaction fails due to an error in **pmemobj_tx_begin**(), +or if the transaction is aborted. This block is optional, but in practice +it should not be omitted. If it is desirable to crash the application when a +transaction aborts and there is no **TX_ONABORT** section, the application can +define the **POBJ_TX_CRASH_ON_NO_ONABORT** macro before inclusion of +**\**. This provides a default **TX_ONABORT** section which +just calls **abort**(3). + +The **TX_ONCOMMIT** macro starts a block of code that will be executed only +if the transaction is successfully committed, which means that the execution +of code in the **TX_BEGIN**() block has not been interrupted by an error or by +a call to **pmemobj_tx_abort**(). This block is optional. + +The **TX_FINALLY** macro starts a block of code that will be executed regardless +of whether the transaction is committed or aborted. This block is optional. + +The **TX_END** macro cleans up and closes the transaction started by the +**TX_BEGIN**() / **TX_BEGIN_PARAM**() / **TX_BEGIN_CB**() macros. +It is mandatory to terminate each transaction with this macro. If the transaction +was aborted, *errno* is set appropriately. + +## TRANSACTION LOG TUNING ## + +From libpmemobj implementation perspective there are two types of operations +in a transaction: + ++ **snapshots**, where action must be persisted immediately, ++ **intents**, where action can be persisted at the transaction commit phase + +**pmemobj_tx_add_range**(3) and all its variants belong to the **snapshots** +group. + +**pmemobj_tx_alloc**(3) (with its variants), **pmemobj_tx_free**(3), +**pmemobj_tx_realloc**(3) (with its variants) and **pmemobj_tx_publish**(3) +belong to the **intents** group. Even though **pmemobj_tx_alloc**() allocates +memory immediately, it modifies only the runtime state and postpones persistent +memory modifications to the commit phase. **pmemobj_tx_free**(3) cannot free +the object immediately, because of possible transaction rollback, so it +postpones both the action and persistent memory modifications to the commit +phase. **pmemobj_tx_realloc**(3) is just a combination of those two. +**pmemobj_tx_publish**(3) postpones reservations and deferred frees to +the commit phase. + +Those two types of operations (snapshots and intents) require that libpmemobj +builds a persistent log of operations. Intent log (also known as a "redo log") +is applied on commit and snapshot log (also known as an "undo log") +is applied on abort. + +When libpmemobj transaction starts, it's not possible to predict how much +persistent memory space will be needed for those logs. This means that libpmemobj +must internally allocate this space whenever it's needed. This has two downsides: + ++ when transaction snapshots a lot of memory or does a lot of allocations, + libpmemobj may need to do many internal allocations, which must be freed when + transaction ends, adding time overhead when big transactions are frequent, ++ transactions can start to fail due to not enough space for logs - this can + be especially problematic for transactions that want to **deallocate** + objects, as those might also fail + +To solve both of these problems libpmemobj exposes the following functions: + ++ **pmemobj_tx_log_append_buffer**(), ++ **pmemobj_tx_xlog_append_buffer**(), ++ **pmemobj_tx_log_auto_alloc**() + +**pmemobj_tx_log_append_buffer**() appends a given range of memory +[*addr*, *addr* + *size*) to the log *type* of the current transaction. +*type* can be one of the two values (with meanings described above): + ++ **TX_LOG_TYPE_SNAPSHOT**, ++ **TX_LOG_TYPE_INTENT** + +The range of memory **must** belong to the same pool the transaction is on and +**must not** be used by more than one thread at the same time. The latter +condition can be verified with tx.debug.verify_user_buffers ctl (see +**pmemobj_ctl_get**(3)). + +The **pmemobj_tx_xlog_append_buffer**() function behaves exactly the same as +**pmemobj_tx_log_append_buffer**() when *flags* equals zero. +*flags* is a bitmask of the following values: + ++ **POBJ_XLOG_APPEND_BUFFER_NO_ABORT** - if the function does not end successfully, +do not abort the transaction. + +**pmemobj_tx_log_snapshots_max_size** calculates the **maximum** size of +a buffer which will be able to hold *nsizes* snapshots, each of size *sizes[i]*. +Application should not expect this function to return the same value between +restarts. In future versions of libpmemobj this function can return smaller +(because of better accuracy or space optimizations) or higher (because +of higher alignment required for better performance) value. This function +is independent of transaction stage and can be called both inside and outside +of transaction. If the returned value S is greater than +**PMEMOBJ_MAX_ALLOC_SIZE**, the buffer should be split into N chunks of size +**PMEMOBJ_MAX_ALLOC_SIZE**, where N is equal to (S / **PMEMOBJ_MAX_ALLOC_SIZE**) +(rounded down) and the last chunk of size (S - (N * **PMEMOBJ_MAX_ALLOC_SIZE**)). + +**pmemobj_tx_log_intents_max_size** calculates the **maximum** size of +a buffer which will be able to hold *nintents* intents. +Just like with **pmemobj_tx_log_snapshots_max_size**, application should not +expect this function to return the same value between restarts, for the same +reasons. This function is independent of transaction stage and can be called +both inside and outside of transaction. + +**pmemobj_tx_log_auto_alloc**() disables (*on_off* set to 0) or enables +(*on_off* set to 1) automatic allocation of internal logs of given *type*. +It can be used to verify that the buffer set with +**pmemobj_tx_log_append_buffer**() is big enough to hold the log, without +reaching out-of-space scenario. + +The **pmemobj_tx_set_user_data**() function associates custom volatile state, +represented by pointer *data*, with the current transaction. This state can +later be retrieved using **pmemobj_tx_get_user_data**() function. +If **pmemobj_tx_set_user_data**() was not called for a current transaction, +**pmemobj_tx_get_user_data**() will return NULL. These functions must be called +during **TX_STAGE_WORK** or **TX_STAGE_ONABORT** or **TX_STAGE_ONCOMMIT** or +**TX_STAGE_FINALLY**. + +**pmemobj_tx_set_failure_behavior**() specifies what should happen in case of an error +within the transaction. It only affects functions which take a NO_ABORT flag. +If **pmemobj_tx_set_failure_behavior**() is called with POBJ_TX_FAILURE_RETURN a NO_ABORT +flag is implicitly passed to all functions which accept this flag. If called +with POBJ_TX_FAILURE_ABORT then all functions abort the transaction (unless NO_ABORT +flag is passed explicitly). This setting is inherited by inner transactions. It does +not affect any of the outer transactions. Aborting on failure is the default behavior. +**pmemobj_tx_get_failure_behavior**() returns failure behavior for the current transaction. +Both **pmemobj_tx_set_failure_behavior**() and **pmemobj_tx_get_failure_behavior**() +must be called during **TX_STAGE_WORK**. + +# RETURN VALUE # + +The **pmemobj_tx_stage**() function returns the stage of the current transaction +stage for a thread. + +On success, **pmemobj_tx_begin**() returns 0. Otherwise, an error number is +returned. + +The **pmemobj_tx_begin**() and **pmemobj_tx_lock**() functions return zero +if *lockp* is successfully added to the transaction. Otherwise, an error number +is returned. + +The **pmemobj_tx_xlock**() function return zero if *lockp* is successfully +added to the transaction. Otherwise, the error number is returned, **errno** is set +and when flags do not contain **POBJ_XLOCK_NO_ABORT**, the transaction is aborted. + +The **pmemobj_tx_abort**() and **pmemobj_tx_commit**() functions return no value. + +The **pmemobj_tx_end**() function returns 0 if the transaction was successful. +Otherwise it returns the error code set by **pmemobj_tx_abort**(). +Note that **pmemobj_tx_abort**() can be called internally by the library. + +The **pmemobj_tx_errno**() function returns the error code of the last transaction. + +The **pmemobj_tx_process**() function returns no value. + +On success, **pmemobj_tx_log_append_buffer**() returns 0. Otherwise, +the stage is changed to **TX_STAGE_ONABORT**, **errno** is set appropriately +and transaction is aborted. + +On success, **pmemobj_tx_xlog_append_buffer**() returns 0. Otherwise, +the error number is returned, **errno** is set and when flags do not contain +**POBJ_XLOG_NO_ABORT**, the transaction is aborted. + +On success, **pmemobj_tx_log_auto_alloc**() returns 0. Otherwise, +the transaction is aborted and an error number is returned. + +On success, **pmemobj_tx_log_snapshots_max_size**() returns size of the buffer. +On failure it returns *SIZE_MAX* and sets *errno* appropriately. + +On success, **pmemobj_tx_log_intents_max_size**() returns size of the buffer. +On failure it returns *SIZE_MAX* and sets *errno* appropriately. + +# CAVEATS # + +Transaction flow control is governed by the **setjmp**(3) and **longjmp**(3) +macros, and they are used in both the macro and function flavors of the API. +The transaction will longjmp on transaction abort. This has one major drawback, +which is described in the ISO C standard subsection 7.13.2.1. It says that +**the values of objects of automatic storage duration that are local to the +function containing the setjmp invocation that do not have volatile-qualified +type and have been changed between the setjmp invocation and longjmp call are +indeterminate.** + +The following example illustrates the issue described above. + +```c +int *bad_example_1 = (int *)0xBAADF00D; +int *bad_example_2 = (int *)0xBAADF00D; +int *bad_example_3 = (int *)0xBAADF00D; +int * volatile good_example = (int *)0xBAADF00D; + +TX_BEGIN(pop) { + bad_example_1 = malloc(sizeof(int)); + bad_example_2 = malloc(sizeof(int)); + bad_example_3 = malloc(sizeof(int)); + good_example = malloc(sizeof(int)); + + /* manual or library abort called here */ + pmemobj_tx_abort(EINVAL); +} TX_ONCOMMIT { + /* + * This section is longjmp-safe + */ +} TX_ONABORT { + /* + * This section is not longjmp-safe + */ + free(good_example); /* OK */ + free(bad_example_1); /* undefined behavior */ +} TX_FINALLY { + /* + * This section is not longjmp-safe on transaction abort only + */ + free(bad_example_2); /* undefined behavior */ +} TX_END + +free(bad_example_3); /* undefined behavior */ +``` + +Objects which are not volatile-qualified, are of automatic storage duration +and have been changed between the invocations of **setjmp**(3) and +**longjmp**(3) (that also means within the work section of the transaction +after **TX_BEGIN**()) should not be used after a transaction abort, or should +be used with utmost care. This also includes code after the **TX_END** macro. + +**libpmemobj**(7) is not cancellation-safe. The pool will never be corrupted +because of a canceled thread, but other threads may stall waiting on locks +taken by that thread. If the application wants to use **pthread_cancel**(3), +it must disable cancellation before calling any **libpmemobj**(7) APIs (see +**pthread_setcancelstate**(3) with **PTHREAD_CANCEL_DISABLE**), and re-enable +it afterwards. Deferring cancellation (**pthread_setcanceltype**(3) with +**PTHREAD_CANCEL_DEFERRED**) is not safe enough, because **libpmemobj**(7) +internally may call functions that are specified as cancellation points in POSIX. + +**libpmemobj**(7) relies on the library destructor being called from the main +thread. For this reason, all functions that might trigger destruction (e.g. +**dlclose**(3)) should be called in the main thread. Otherwise some of the +resources associated with that thread might not be cleaned up properly. + +# SEE ALSO # + +**dlclose**(3), **longjmp**(3), **pmemobj_tx_add_range**(3), +**pmemobj_tx_alloc**(3), **pthread_setcancelstate**(3), +**pthread_setcanceltype**(3), **setjmp**(3), +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_layout_begin.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_layout_begin.3.md new file mode 100644 index 0000000000..f3a00da684 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_layout_begin.3.md @@ -0,0 +1,105 @@ +--- +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_layout_begin.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pobj_layout_begin.3 -- man page for declaration of pool's layout) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[EXAMPLE](#example)
+[SEE ALSO](#see-also)
+ +# NAME # + +**POBJ_LAYOUT_BEGIN**(), **POBJ_LAYOUT_TOID**(), +**POBJ_LAYOUT_ROOT**(), **POBJ_LAYOUT_NAME**(), +**POBJ_LAYOUT_END**(), **POBJ_LAYOUT_TYPES_NUM**() +- persistent memory transactional object store layout + +# SYNOPSIS # + +```c +#include + +POBJ_LAYOUT_BEGIN(layout) +POBJ_LAYOUT_TOID(layout, TYPE) +POBJ_LAYOUT_ROOT(layout, ROOT_TYPE) +POBJ_LAYOUT_NAME(layout) +POBJ_LAYOUT_END(layout) +POBJ_LAYOUT_TYPES_NUM(layout) +``` + +# DESCRIPTION # + +**libpmemobj**(7) defines a set of macros for convenient declaration of a +pool's layout. The layout declaration consists of declarations of a number of +used types. The declared types will be assigned consecutive type numbers. +Declared types may be used in conjunction with type safety macros (see +**TOID_DECLARE**(3)). Once created, the layout declaration must not be changed +unless any new types are added at the end of the existing layout declaration. +Modifying any existing declaration may lead to changes in the type numbers of +declared types, which in consequence may cause data corruption. + +The **POBJ_LAYOUT_BEGIN**() macro indicates a begin of declaration of layout. +The *LAYOUT* argument is a name of layout. This argument must be passed to all macros +related to the declaration of layout. + +The **POBJ_LAYOUT_TOID**() macro declares a typed *OID* for type passed as *TYPE* argument +inside the declaration of layout. All types declared using this macro are assigned with +consecutive type numbers. This macro must be used between the **POBJ_LAYOUT_BEGIN**() +and **POBJ_LAYOUT_END**() macros, with the same name passed as *LAYOUT* argument. + +The **POBJ_LAYOUT_ROOT**() macro declares a typed *OID* for type passed as *ROOT_TYPE* +argument inside the declaration of layout. The typed *OID* will be assigned with type number +for root object **POBJ_ROOT_TYPE_NUM**. + +The **POBJ_LAYOUT_END**() macro ends the declaration of layout. + +The **POBJ_LAYOUT_NAME**() macro returns the name of layout as a null-terminated string. + +The **POBJ_LAYOUT_TYPES_NUM**() macro returns number of types declared using the **POBJ_LAYOUT_TOID**() +macro within the layout declaration. + +# EXAMPLE # + +This is an example of layout declaration: + +```c +POBJ_LAYOUT_BEGIN(mylayout); +POBJ_LAYOUT_ROOT(mylayout, struct root); +POBJ_LAYOUT_TOID(mylayout, struct node); +POBJ_LAYOUT_TOID(mylayout, struct foo); +POBJ_LAYOUT_END(mylayout); + +struct root +{ + TOID(struct node) node; +}; + +struct node +{ + TOID(struct node) next; + TOID(struct foo) foo; +}; +``` + +The name of layout and the number of declared types can be retrieved using the following code: + +```c +const char *layout_name = POBJ_LAYOUT_NAME(mylayout); +int num_of_types = POBJ_LAYOUT_TYPES_NUM(mylayout); +``` + +# SEE ALSO # + +**TOID_DECLARE**(3), **libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_list_head.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_list_head.3.md new file mode 100644 index 0000000000..9922ccc077 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/pobj_list_head.3.md @@ -0,0 +1,252 @@ +--- +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_list_head.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (pobj_list_head.3 -- man page for type-safe non-transactional persistent atomic lists) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[SEE ALSO](#see-also)
+ +# NAME # + +**POBJ_LIST_HEAD**(), +**POBJ_LIST_ENTRY**(), +**POBJ_LIST_FIRST**(), +**POBJ_LIST_LAST**(), +**POBJ_LIST_EMPTY**(), +**POBJ_LIST_NEXT**(), +**POBJ_LIST_PREV**(), + +**POBJ_LIST_FOREACH**(), +**POBJ_LIST_FOREACH_REVERSE**(), + +**POBJ_LIST_INSERT_HEAD**(), +**POBJ_LIST_INSERT_TAIL**(), +**POBJ_LIST_INSERT_AFTER**(), +**POBJ_LIST_INSERT_BEFORE**(), +**POBJ_LIST_INSERT_NEW_HEAD**(), +**POBJ_LIST_INSERT_NEW_TAIL**(), +**POBJ_LIST_INSERT_NEW_AFTER**(), +**POBJ_LIST_INSERT_NEW_BEFORE**(), + +**POBJ_LIST_REMOVE**(), +**POBJ_LIST_REMOVE_FREE**(), + +**POBJ_LIST_MOVE_ELEMENT_HEAD**(), +**POBJ_LIST_MOVE_ELEMENT_TAIL**(), +**POBJ_LIST_MOVE_ELEMENT_AFTER**(), +**POBJ_LIST_MOVE_ELEMENT_BEFORE**() +- type-safe non-transactional persistent atomic lists + +# SYNOPSIS # + +```c +#include + +POBJ_LIST_HEAD(HEADNAME, TYPE) +POBJ_LIST_ENTRY(TYPE) +POBJ_LIST_FIRST(POBJ_LIST_HEAD *head) +POBJ_LIST_LAST(POBJ_LIST_HEAD *head, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_EMPTY(POBJ_LIST_HEAD *head) +POBJ_LIST_NEXT(TOID elm, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_PREV(TOID elm, POBJ_LIST_ENTRY FIELD) + +POBJ_LIST_FOREACH(TOID var, POBJ_LIST_HEAD *head, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_FOREACH_REVERSE(TOID var, POBJ_LIST_HEAD *head, POBJ_LIST_ENTRY FIELD) + +POBJ_LIST_INSERT_HEAD(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID elm, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_INSERT_TAIL(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID elm, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_INSERT_AFTER(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID listelm, TOID elm, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_INSERT_BEFORE(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID listelm, TOID elm, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_INSERT_NEW_HEAD(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + POBJ_LIST_ENTRY FIELD, size_t size, + pmemobj_constr constructor, void *arg) +POBJ_LIST_INSERT_NEW_TAIL(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + POBJ_LIST_ENTRY FIELD, size_t size, + pmemobj_constr constructor, void *arg) +POBJ_LIST_INSERT_NEW_AFTER(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID listelm, POBJ_LIST_ENTRY FIELD, size_t size, + pmemobj_constr constructor, void *arg) +POBJ_LIST_INSERT_NEW_BEFORE(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID listelm, POBJ_LIST_ENTRY FIELD, size_t size, + pmemobj_constr constructor, void *arg) + +POBJ_LIST_REMOVE(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID elm, POBJ_LIST_ENTRY FIELD) +POBJ_LIST_REMOVE_FREE(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + TOID elm, POBJ_LIST_ENTRY FIELD) + +POBJ_LIST_MOVE_ELEMENT_HEAD(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + POBJ_LIST_HEAD *head_new, TOID elm, POBJ_LIST_ENTRY FIELD, + POBJ_LIST_ENTRY field_new) +POBJ_LIST_MOVE_ELEMENT_TAIL(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + POBJ_LIST_HEAD *head_new, TOID elm, POBJ_LIST_ENTRY FIELD, + POBJ_LIST_ENTRY field_new) +POBJ_LIST_MOVE_ELEMENT_AFTER(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + POBJ_LIST_HEAD *head_new, TOID listelm, TOID elm, + POBJ_LIST_ENTRY FIELD, POBJ_LIST_ENTRY field_new) +POBJ_LIST_MOVE_ELEMENT_BEFORE(PMEMobjpool *pop, POBJ_LIST_HEAD *head, + POBJ_LIST_HEAD *head_new, TOID listelm, TOID elm, + POBJ_LIST_ENTRY FIELD, POBJ_LIST_ENTRY field_new) +``` + +# DESCRIPTION # + +The following macros define and operate on a type-safe persistent +atomic circular doubly linked list data structure that consist of +a set of persistent objects of a well-known type. Unlike the functions +described in the previous section, these macros provide type enforcement +by requiring declaration of type of the objects stored in given list, +and not allowing mixing objects of different types in a single list. + +The functionality and semantics of those macros is similar to circular +queues defined in **queue**(3). + +The majority of the macros must specify the handle to the memory pool *pop* and +the name of the *field* in the user-defined structure, which must be of type +*POBJ_LIST_ENTRY* and is used to connect the elements in the list. + +A list is headed by a structure defined by the **POBJ_LIST_HEAD**() macro. +This structure contains an object handle of the first element on the list. +The elements are doubly linked so that an arbitrary element can be removed +without a need to traverse the list. New elements can be added to the list +before or after an existing element, at the head of the list, or at the end +of the list. A list may be traversed in either direction. A *POBJ_LIST_HEAD* +structure is declared as follows: + +```c +#define POBJ_LIST_HEAD(HEADNAME, TYPE) +struct HEADNAME +{ + TOID(TYPE) pe_first; + PMEMmutex lock; +}; +``` + +In the macro definitions, *TYPE* is the name of a user-defined structure, +that must contain a field of type *POBJ_LIST_ENTRY*. The argument *HEADNAME* +is the name of a user-defined structure that must be declared using the macro +*POBJ_LIST_HEAD*. See the examples below for further explanation of how these +macros are used. + +The macro *POBJ_LIST_ENTRY* declares a structure that connects the elements +in the list. + +```c +#define POBJ_LIST_ENTRY(TYPE) +struct +{ + TOID(TYPE) pe_next; + TOID(TYPE) pe_prev; +}; +``` + +The macro **POBJ_LIST_FIRST**() returns the first element on the list +referenced by *head*. If the list is empty **OID_NULL** is returned. + +The macro **POBJ_LIST_LAST**() returns the last element on the list +referenced by *head*. If the list is empty **OID_NULL** is returned. + +The macro **POBJ_LIST_EMPTY**() evaluates to 1 if the list referenced +by *head* is empty. Otherwise, 0 is returned. + +The macro **POBJ_LIST_NEXT**() returns the element next to the element *elm*. + +The macro **POBJ_LIST_PREV**() returns the element preceding the element *elm*. + +The macro **POBJ_LIST_FOREACH**() traverses the list referenced by *head* +assigning a handle to each element in turn to *var* variable. + +The macro **POBJ_LIST_FOREACH_REVERSE**() traverses the list referenced +by *head* in reverse order, assigning a handle to each element in turn to +*var* variable. The *field* argument is the name of the field of type +*POBJ_LIST_ENTRY* in the element structure. + +The macro **POBJ_LIST_INSERT_HEAD**() inserts the element *elm* at the head +of the list referenced by *head*. + +The macro **POBJ_LIST_INSERT_TAIL**() inserts the element *elm* at the end +of the list referenced by *head*. + +The macro **POBJ_LIST_INSERT_AFTER**() inserts the element *elm* into +the list referenced by *head* after the element *listelm*. If *listelm* +value is **TOID_NULL**, the object is inserted at the end of the list. + +The macro **POBJ_LIST_INSERT_BEFORE**() inserts the element *elm* into +the list referenced by *head* before the element *listelm*. If *listelm* +value is **TOID_NULL**, the object is inserted at the head of the list. + +The macro **POBJ_LIST_INSERT_NEW_HEAD**() atomically allocates a new +object of size *size* and inserts it at the head of the list referenced +by *head*. The newly allocated object is also added to the internal object +container associated with a type number which is retrieved from the typed +*OID* of the first element on list. + +The macro **POBJ_LIST_INSERT_NEW_TAIL**() atomically allocates a new +object of size *size* and inserts it at the tail of the list referenced +by *head*. The newly allocated object is also added to the internal object +container associated with a type number which is retrieved from +the typed *OID* of the first element on list. + +The macro **POBJ_LIST_INSERT_NEW_AFTER**() atomically allocates a new +object of size *size* and inserts it into the list referenced by *head* +after the element *listelm*. If *listelm* value is **TOID_NULL**, +the object is inserted at the end of the list. The newly allocated object +is also added to the internal object container associated with with a type +number which is retrieved from the typed *OID* of the first element on list. + +The macro **POBJ_LIST_INSERT_NEW_BEFORE**() atomically allocates a new +object of size *size* and inserts it into the list referenced by *head* +before the element *listelm*. If *listelm* value is **TOID_NULL**, +the object is inserted at the head of the list. The newly allocated object +is also added to the internal object container associated with with a type +number which is retrieved from the typed *OID* of the first element on list. + +The macro **POBJ_LIST_REMOVE**() removes the element *elm* from the list +referenced by *head*. + +The macro **POBJ_LIST_REMOVE_FREE**() removes the element *elm* from the list +referenced by *head* and frees the memory space represented by this element. + +The macro **POBJ_LIST_MOVE_ELEMENT_HEAD**() moves the element *elm* from the +list referenced by *head* to the head of the list *head_new*. The *field* and +*field_new* arguments are the names of the fields of type *POBJ_LIST_ENTRY* in +the element structure that are used to connect the elements in both lists. + +The macro **POBJ_LIST_MOVE_ELEMENT_TAIL**() moves the element *elm* from the +list referenced by *head* to the end of the list *head_new*. The *field* and +*field_new* arguments are the names of the fields of type *POBJ_LIST_ENTRY* in +the element structure that are used to connect the elements in both lists. + +The macro **POBJ_LIST_MOVE_ELEMENT_AFTER**() atomically removes the element *elm* +from the list referenced by *head* and inserts it into the list referenced by +*head_new* after the element *listelm*. If *listelm* value is *TOID_NULL*, +the object is inserted at the end of the list. The *field* and *field_new* +arguments are the names of the fields of type *POBJ_LIST_ENTRY* in the element +structure that are used to connect the elements in both lists. + +The macro **POBJ_LIST_MOVE_ELEMENT_BEFORE**() atomically removes the element +*elm* from the list referenced by *head* and inserts it into the list referenced +by *head_new* before the element *listelm*. If *listelm* value is **TOID_NULL**, +the object is inserted at the head of the list. The *field* and *field_new* +arguments are the names of the fields of type *POBJ_LIST_ENTRY* in the element +structure that are used to connect the elements in both lists. + +# SEE ALSO # + +**queue**(3), **libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmemobj/toid_declare.3.md b/content/pmdk/manpages/linux/v2.0/libpmemobj/toid_declare.3.md new file mode 100644 index 0000000000..634527dd8c --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmemobj/toid_declare.3.md @@ -0,0 +1,110 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["toid_declare.3.html"] +title: "libpmemobj | PMDK" +header: "pmemobj API version 2.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2018, Intel Corporation) + +[comment]: <> (toid_declare.3 -- man page for obj type safety mechanism) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[SEE ALSO](#see-also)
+ +# NAME # + +**TOID_DECLARE**(), **TOID_DECLARE_ROOT**(), **TOID**(), +**TOID_TYPE_NUM**(), **TOID_TYPE_NUM_OF**(), **TOID_VALID**(), +**OID_INSTANCEOF**(), **TOID_ASSIGN**(), **TOID_IS_NULL**(), +**TOID_EQUALS**(), **TOID_TYPEOF**(), **TOID_OFFSETOF**(), +**DIRECT_RW**(), **D_RW**(), **DIRECT_RO**(), +**D_RO**() - libpmemobj type safety mechanism + +# SYNOPSIS # + +```c +#include + +TOID_DECLARE(TYPE, uint64_t type_num) +TOID_DECLARE_ROOT(ROOT_TYPE) +TOID(TYPE) +TOID_TYPE_NUM(TYPE) +TOID_TYPE_NUM_OF(TOID oid) +TOID_VALID(TOID oid) +OID_INSTANCEOF(PMEMoid oid, TYPE) +TOID_ASSIGN(TOID o, VALUE) +TOID_IS_NULL(TOID o) +TOID_EQUALS(TOID lhs, TOID rhs) +TOID_TYPEOF(TOID o) +TOID_OFFSETOF(TOID o, FILED) +DIRECT_RW(TOID oid) +D_RW(TOID oid) +DIRECT_RO(TOID oid) +D_RO(TOID oid) +``` + +# DESCRIPTION # + +Operating on untyped object handles, as well as on direct untyped object +pointers (*void\**), may be confusing and error-prone. To facilitate +type safety, **libpmemobj**(7) defines a set of macros that provide static +type enforcement, catching potential errors at compile time. For example, +a compile-time error is generated when an attempt is made to assign a handle to +an object of one type to the object handle variable of another type of object. + +The **TOID_DECLARE**() macro declares a typed *OID* of user-defined type +*TYPE* and type number *type_num*. + +The **TOID_DECLARE_ROOT**() macro declares a typed *OID* of user-defined type +*ROOT_TYPE* and root object type number **POBJ_ROOT_TYPE_NUM**. + +The **TOID**() macro declares a handle to an object of type *TYPE*, +where *TYPE* is the name of a user-defined structure. The typed *OID* must +be declared first using the **TOID_DECLARE**(), **TOID_DECLARE_ROOT**(), +**POBJ_LAYOUT_TOID**(3) or **POBJ_LAYOUT_ROOT**(3) macros. + +The **TOID_TYPE_NUM**() macro returns the type number of the type specified +by *TYPE*. + +The **TOID_TYPE_NUM_OF**() macro returns the type number of the object +specified by *oid*. The type number is read from the typed *OID*. + +The **TOID_VALID**() macro validates whether the type number stored in +the object's metadata is equal to the type number read from the typed *OID*. + +The **OID_INSTANCEOF**() macro checks whether the *oid* is of type *TYPE*. + +The **TOID_ASSIGN**() macro assigns the object handle *VALUE* to typed *OID* +*o*. + +The **TOID_IS_NULL**() macro evaluates to true if the object handle +represented by *o* is **OID_NULL**. + +The **TOID_EQUALS**() macro evaluates to true if both the *lhs* and *rhs* +object handles reference the same persistent object. + +The **TOID_TYPEOF**() macro returns the type of the object handle represented +by typed *OID* *o*. + +The **TOID_OFFSETOF**() macro returns the offset of the *FIELD* member from +the start of the object represented by *o*. + +The **DIRECT_RW**() macro and its shortened form **D_RW**() return a typed +write pointer (*TYPE\**) to an object represented by *oid*. If *oid* is +**OID_NULL**, the macro evaluates to NULL. + +The **DIRECT_RO**() macro and its shortened form **D_RO**() return a typed +read-only (const) pointer (*TYPE\**) to an object represented by *oid*. If +*oid* is **OID_NULL**, the macro evaluates to NULL. + +# SEE ALSO # + +**OID_IS_NULL**(3), **POBJ_LAYOUT_ROOT**(3), **POBJ_LAYOUT_TOID**(3), +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmempool/libpmempool.7.md b/content/pmdk/manpages/linux/v2.0/libpmempool/libpmempool.7.md new file mode 100644 index 0000000000..6bbfb7e5a1 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmempool/libpmempool.7.md @@ -0,0 +1,268 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["libpmempool.7.html"] +title: "libpmempool | PMDK" +header: "pmempool API version 1.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (libpmempool.7 -- man page for libpmempool) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[LIBRARY API VERSIONING](#library-api-versioning-1)
+[DEBUGGING AND ERROR HANDLING](#debugging-and-error-handling)
+[EXAMPLE](#example)
+[ACKNOWLEDGEMENTS](#acknowledgements)
+[SEE ALSO](#see-also)
+ +# NAME # + +**libpmempool** - persistent memory pool management library + +# SYNOPSIS # + +```c +#include +cc -std=gnu99 ... -lpmempool -lpmem +``` + +##### Library API versioning: ##### + +```c +const char *pmempool_check_version( + unsigned major_required, + unsigned minor_required); +``` + +##### Error handling: ##### + +```c +const char *pmempool_errormsg(void); +``` + +##### Other library functions: ##### + +A description of other **libpmempool** functions can be found on the following +manual pages: + ++ health check functions: **pmempool_check_init**(3) + ++ pool set synchronization and transformation: **pmempool_sync**(3) + ++ pool set management functions: **pmempool_rm**(3) + ++ toggle or query pool set features: **pmempool_feature_query**(3) + +# DESCRIPTION # + +**libpmempool** +provides a set of utilities for off-line analysis and +manipulation of a *pool*. A *pool* in this +manpage means a pmemobj pool independent of the underlying storage. Some +**libpmempool** functions are required to work without +any impact on the *pool* but some may create a new or modify +an existing *pool*. + +**libpmempool** +is for applications that need high reliability or built-in +troubleshooting. It may be useful for testing and debugging +purposes also. + +**libpmempool** introduces functionality of pool set health check, +synchronization, transformation and removal. + +# CAVEATS # + +**libpmempool** relies on the library destructor being called from the main +thread. For this reason, all functions that might trigger destruction (e.g. +**dlclose**(3)) should be called in the main thread. Otherwise some of the +resources associated with that thread might not be cleaned up properly. + +**libpmempool** requires the **-std=gnu99** compilation flag to +build properly. + +# LIBRARY API VERSIONING # + +This section describes how the library API is versioned, +allowing applications to work with an evolving API. + +The **pmempool_check_version**() function is used to see if +the installed **libpmempool** supports the version of the +library API required by an application. The easiest way to +do this for the application is to supply the compile-time +version information, supplied by defines in **\**, like this: + +```c +reason = pmempool_check_version(PMEMPOOL_MAJOR_VERSION, + PMEMPOOL_MINOR_VERSION); +if (reason != NULL) { + /* version check failed, reason string tells you why */ +} +``` + +Any mismatch in the major version number is considered a failure, but a +library with a newer minor version number will pass this +check since increasing minor versions imply backwards compatibility. + +An application can also check specifically for the existence of an +interface by checking for the version where that interface +was introduced. These versions are documented in this man +page as follows: unless otherwise specified, all interfaces +described here are available in version 1.0 of the library. +Interfaces added after version 1.0 will contain the text +*introduced in version x.y* in the section of this manual +describing the feature. + +When the version check performed by **pmempool_check_version**() +is successful, the return value is NULL. Otherwise the +return value is a static string describing the reason for +failing the version check. The string returned by +**pmempool_check_version**() must not be modified or freed. + +# DEBUGGING AND ERROR HANDLING # + +If an error is detected during the call to a **libpmempool** function, the +application may retrieve an error message describing the reason for the failure +from **pmempool_errormsg**(). This function returns a pointer to a static buffer +containing the last error message logged for the current thread. If *errno* +was set, the error message may include a description of the corresponding +error code as returned by **strerror**(3). The error message buffer is +thread-local; errors encountered in one thread do not affect its value in +other threads. The buffer is never cleared by any library function; its +content is significant only when the return value of the immediately preceding +call to a **libpmempool** 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. + +Two versions of **libpmempool** are typically available on a development +system. The normal version, accessed when a program is linked using the +**-lpmempool** option, is optimized for performance. That version skips checks +that impact performance and never logs any trace information or performs any +run-time assertions. + +A second version of **libpmempool**, accessed when a program uses the libraries +under **/usr/lib/pmdk_debug**, contains run-time assertions and trace points. +The typical way to access the debug version is to set the environment variable +**LD_LIBRARY_PATH** to **/usr/lib/pmdk_debug** or **/usr/lib64/pmdk_debug**, +as appropriate. Debugging output is controlled using the following environment +variables. These variables have no effect on the non-debug version of the library. + ++ **PMEMPOOL_LOG_LEVEL** + +The value of **PMEMPOOL_LOG_LEVEL** enables trace points in the debug version +of the library, as follows: + ++ **0** - This is the default level when **PMEMPOOL_LOG_LEVEL** is not set. +No log messages are emitted at this level. + ++ **1** - Additional details on any errors detected are logged (in addition +to returning the *errno*-based errors as usual). The same information +may be retrieved using **pmempool_errormsg**(). + ++ **2** - A trace of basic operations is logged. + ++ **3** - Enables a very verbose amount of function call tracing in the library. + ++ **4** - Enables voluminous and fairly obscure tracing +information that is likely only useful to the **libpmempool** developers. + +Unless **PMEMPOOL_LOG_FILE** is set, debugging output is written to *stderr*. + ++ **PMEMPOOL_LOG_FILE** + +Specifies the name of a file where +all logging information should be written. 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 **PMEMPOOL_LOG_FILE** is not set, output is +written to *stderr*. + +# EXAMPLE # + +The following example illustrates how the **libpmempool** API is used. +The program detects the type and checks consistency of given pool. +If there are any issues detected, the pool is automatically repaired. + +```c +#include +#include +#include +#include +#include + +#define PATH "./pmem-fs/myfile" +#define CHECK_FLAGS (PMEMPOOL_CHECK_FORMAT_STR|PMEMPOOL_CHECK_REPAIR|\ + PMEMPOOL_CHECK_VERBOSE) + +int +main(int argc, char *argv[]) +{ + PMEMpoolcheck *ppc; + struct pmempool_check_status *status; + enum pmempool_check_result ret; + + /* arguments for check */ + struct pmempool_check_args args = { + .path = PATH, + .backup_path = NULL, + .pool_type = PMEMPOOL_POOL_TYPE_DETECT, + .flags = CHECK_FLAGS + }; + + /* initialize check context */ + if ((ppc = pmempool_check_init(&args, sizeof(args))) == NULL) { + perror("pmempool_check_init"); + exit(EXIT_FAILURE); + } + + /* perform check and repair, answer 'yes' for each question */ + while ((status = pmempool_check(ppc)) != NULL) { + switch (status->type) { + case PMEMPOOL_CHECK_MSG_TYPE_ERROR: + printf("%s\n", status->str.msg); + break; + case PMEMPOOL_CHECK_MSG_TYPE_INFO: + printf("%s\n", status->str.msg); + break; + case PMEMPOOL_CHECK_MSG_TYPE_QUESTION: + printf("%s\n", status->str.msg); + status->str.answer = "yes"; + break; + default: + pmempool_check_end(ppc); + exit(EXIT_FAILURE); + } + } + + /* finalize the check and get the result */ + ret = pmempool_check_end(ppc); + switch (ret) { + case PMEMPOOL_CHECK_RESULT_CONSISTENT: + case PMEMPOOL_CHECK_RESULT_REPAIRED: + return 0; + default: + return 1; + } +} +``` + +See for more examples using the +**libpmempool** API. + +# ACKNOWLEDGEMENTS # + +**libpmempool** builds on the persistent memory programming model +recommended by the SNIA NVM Programming Technical Work Group: + + +# SEE ALSO # + +**dlclose**(3), **pmempool_check_init**(3), **pmempool_feature_query**(3), +**pmempool_rm**(3), **pmempool_sync**(3), **strerror**(3), **libpmem**(7), +**libpmemobj**(7)** and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_check_init.3.md b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_check_init.3.md new file mode 100644 index 0000000000..5b0503d43e --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_check_init.3.md @@ -0,0 +1,208 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool_check_init.3.html"] +title: "libpmempool | PMDK" +header: "pmempool API version 1.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2022, Intel Corporation) + +[comment]: <> (pmempool_check_init.3 -- man page for pmempool health check functions) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[EXAMPLE](#example)
+[NOTES](#notes)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool_check_init**(), **pmempool_check**(), +**pmempool_check_end**() - checks pmempool health + +# SYNOPSIS # + +```c +#include + +PMEMpoolcheck *pmempool_check_init(struct pmempool_check_args *args, + size_t args_size); +struct pmempool_check_status *pmempool_check(PMEMpoolcheck *ppc); +enum pmempool_check_result pmempool_check_end(PMEMpoolcheck *ppc); +``` + +# DESCRIPTION # + +To perform the checks provided by **libpmempool**, a *check context* +must first be initialized using the **pmempool_check_init**() +function described in this section. Once initialized, the +*check context* is represented by an opaque handle of +type *PMEMpoolcheck\**, which is passed to all of the +other functions available in **libpmempool** + +To execute checks, **pmempool_check**() must be called iteratively. +Each call generates a new check status, represented by a +*struct pmempool_check_status* structure. Status messages are described +later below. + +When the checks are completed, **pmempool_check**() returns NULL. The check +must be finalized using **pmempool_check_end**(), which returns an +*enum pmempool_check_result* describing the results of the entire check. + +**pmempool_check_init**() initializes the check context. *args* describes +parameters of the check context. *args_size* should be equal to the size of +the *struct pmempool_check_args*. *struct pmempool_check_args* is defined as follows: + +```c +struct pmempool_check_args +{ + /* path to the pool to check */ + const char *path; + + /* optional backup path */ + const char *backup_path; + + /* type of the pool */ + enum pmempool_pool_type pool_type; + + /* parameters */ + int flags; +}; +``` + +The *flags* argument accepts any combination of the following values (ORed): + ++ **PMEMPOOL_CHECK_REPAIR** - perform repairs + ++ **PMEMPOOL_CHECK_DRY_RUN** - emulate repairs, not supported on Device DAX + ++ **PMEMPOOL_CHECK_ADVANCED** - perform hazardous repairs + ++ **PMEMPOOL_CHECK_ALWAYS_YES** - do not ask before repairs + ++ **PMEMPOOL_CHECK_VERBOSE** - generate info statuses + ++ **PMEMPOOL_CHECK_FORMAT_STR** - generate string format statuses + +*pool_type* must match the type of the *pool* being processed. Pool type +detection may be enabled by setting *pool_type* to +**PMEMPOOL_POOL_TYPE_DETECT**. A pool type detection failure ends the check. + +*backup_path* may be: + ++ NULL. No backup will be performed. + ++ a non-existent file: *backup_path* will be created and backup will be +performed. *path* must be a single file *pool*. + ++ an existing *pool set* file: Backup will be performed as defined by the +*backup_path* pool set. *path* must be a pool set, and *backup_path* must have +the same structure (the same number of parts with exactly the same size) as the +*path* pool set. + +Backup is supported only if the source *pool set* has no defined replicas. + +The **pmempool_check**() function starts or resumes the check indicated by *ppc*. +When the next status is generated, the check is paused and **pmempool_check**() +returns a pointer to the *struct pmempool_check_status* structure: + +```c +struct pmempool_check_status +{ + enum pmempool_check_msg_type type; /* type of the status */ + struct + { + const char *msg; /* status message string */ + const char *answer; /* answer to message if applicable */ + } str; +}; +``` + +This structure can describe three types of statuses: + ++ **PMEMPOOL_CHECK_MSG_TYPE_INFO** - detailed information about the check. + Generated only if a **PMEMPOOL_CHECK_VERBOSE** flag was set. + ++ **PMEMPOOL_CHECK_MSG_TYPE_ERROR** - An error was encountered. + ++ **PMEMPOOL_CHECK_MSG_TYPE_QUESTION** - question. Generated only if an + **PMEMPOOL_CHECK_ALWAYS_YES** flag was not set. It requires *answer* to be + set to "yes" or "no" before continuing. + +After calling **pmempool_check**() again, the previously provided +*struct pmempool_check_status* pointer must be considered invalid. + +The **pmempool_check_end**() function finalizes the check and releases all +related resources. *ppc* is invalid after calling **pmempool_check_end**(). + +# RETURN VALUE # + +**pmempool_check_init**() returns an opaque handle of type *PMEMpoolcheck\**. +If the provided parameters are invalid or the initialization process fails, +**pmempool_check_init**() returns NULL and sets *errno* appropriately. + +Each call to **pmempool_check**() returns a pointer to a +*struct pmempool_check_status* structure when a status is generated. When the +check completes, **pmempool_check**() returns NULL. + +The **pmempool_check_end**() function returns an *enum pmempool_check_result* +summarizing the results of the finalized check. **pmempool_check_end**() can +return one of the following values: + ++ **PMEMPOOL_CHECK_RESULT_CONSISTENT** - the *pool* is consistent + ++ **PMEMPOOL_CHECK_RESULT_NOT_CONSISTENT** - the *pool* is not consistent + ++ **PMEMPOOL_CHECK_RESULT_REPAIRED** - the *pool* has issues but all repair + steps completed successfully + ++ **PMEMPOOL_CHECK_RESULT_CANNOT_REPAIR** - the *pool* has issues which + can not be repaired + ++ **PMEMPOOL_CHECK_RESULT_ERROR** - the *pool* has errors or the check + encountered an issue + ++ **PMEMPOOL_CHECK_RESULT_SYNC_REQ** - the *pool* has single healthy replica. + To fix remaining issues use **pmempool_sync**(3). + +# EXAMPLE # + +This is an example of a *check context* initialization: + +```c +struct pmempool_check_args args = +{ + .path = "/path/to/obj.pool", + .backup_path = NULL, + .pool_type = PMEMPOOL_POOL_TYPE_OBJ, + .flags = PMEMPOOL_CHECK_VERBOSE | PMEMPOOL_CHECK_FORMAT_STR +}; +``` + +```c +PMEMpoolcheck *ppc = pmempool_check_init(&args, sizeof(args)); +``` + +The check will process a *pool* of type **PMEMPOOL_POOL_TYPE_OBJ** +located in the path */path/to/obj.pool*. Before the check it will +not create a backup of the *pool* (*backup_path == NULL*). +It will also generate +detailed information about the check (**PMEMPOOL_CHECK_VERBOSE**). +The **PMEMPOOL_CHECK_FORMAT_STR** flag indicates string +format statuses (*struct pmempool_check_status*). +Currently this is the only supported status format so this flag is required. + +# NOTES # + +Currently, checking the consistency of a *pmemobj* pool is +**not** supported. + +# SEE ALSO # + +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_feature_query.3.md b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_feature_query.3.md new file mode 100644 index 0000000000..4af1d7c1b0 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_feature_query.3.md @@ -0,0 +1,100 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool_feature_query.3.html"] +title: "libpmempool | PMDK" +header: "pmempool API version 1.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2018-2022, Intel Corporation) + +[comment]: <> (pmempool_feature_query.3 -- man page for toggle and query pool +set features) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[COMPATIBILITY](#compatibility)
+[DISCLAIMER](#disclaimer)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool_feature_query**(), **pmempool_feature_enable**(), +**pmempool_feature_disable**() - toggle or query pool set features + +# SYNOPSIS # + +```c +#include + +int pmempool_feature_query(const char *path, enum pmempool_feature feature, unsigned flags); + +int pmempool_feature_enable(const char *path, enum pmempool_feature feature, unsigned flags); + +int pmempool_feature_disable(const char *path, enum pmempool_feature feature, unsigned flags); +``` + +# DESCRIPTION # + +The *feature* argument accepts following values: + ++ **PMEMPOOL_FEAT_SINGLEHDR** - only the first part in each replica contains the +pool part internal metadata. This value can be used only with +**pmempool_feature_query**(). It can not be enabled or disabled. For details see +**poolset**(5). + ++ **PMEMPOOL_FEAT_CKSUM_2K** - only the first 2KiB of pool part internal metadata +is checksummed. Other features may depend on this one to store additional metadata +in otherwise unused second 2KiB part of a header. +When **PMEMPOOL_FEAT_CKSUM_2K** is disabled whole 4KiB is checksummed. + ++ **PMEMPOOL_FEAT_SHUTDOWN_STATE** - enables additional check performed during +pool open which verifies pool consistency in the presence of dirty shutdown. +**PMEMPOOL_FEAT_CKSUM_2K** has to be enabled prior to +**PMEMPOOL_FEAT_SHUTDOWN_STATE** otherwise enabling **PMEMPOOL_FEAT_SHUTDOWN_STATE** will fail. + ++ **PMEMPOOL_FEAT_CHECK_BAD_BLOCKS** - enables checking bad blocks performed +during opening a pool and fixing bad blocks performed by pmempool-sync +during syncing a pool. For details see **pmempool-feature**(1). + +The **pmempool_feature_query**() function checks state of *feature* in the +pool set pointed by *path*. + +The **pmempool_feature_enable**() function enables *feature* in the pool set +pointed by *path*. + +The **pmempool_feature_disable**() function disables *feature* in the pool set +pointed by *path*. + +# COMPATIBILITY # + +Poolsets with features not defined in this document (e.g. enabled by the newer +software version) are not supported. + +# DISCLAIMER # + +**pmempool_feature_query**(), **pmempool_feature_enable**() and +**pmempool_feature_disable**() are not fail safe. + +# RETURN VALUE # + +On success, **pmempool_feature_query**() returns 0 if *feature* is disabled or +1 if it is enabled. On error, it returns -1 and sets *errno* accordingly. + +On success, **pmempool_feature_enable**() returns 0. On error, it returns -1 +and sets *errno* accordingly. + +On success, **pmempool_feature_disable**() returns 0. On error, it returns -1 +and sets *errno* accordingly. + +If non zero *flags* are provided **errno** is set to EINVAL and function +returns -1. + +# SEE ALSO # + +**poolset**(5) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_rm.3.md b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_rm.3.md new file mode 100644 index 0000000000..e586344f72 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_rm.3.md @@ -0,0 +1,55 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool_rm.3.html"] +title: "libpmempool | PMDK" +header: "pmempool API version 1.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2022, Intel Corporation) + +[comment]: <> (pmempool_rm.3 -- man page for pool set management functions) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool_rm**() - remove persistent memory pool + +# SYNOPSIS # + +```c +#include + +int pmempool_rm(const char *path, int flags); +``` + +# DESCRIPTION # + +The **pmempool_rm**() function removes the pool pointed to by *path*. The *path* +can point to a regular file, device dax or pool set file. If *path* is a pool +set file, **pmempool_rm**() will remove all part files from replicas +using **unlink**(2) before removing the pool set file itself. + +The *flags* argument determines the behavior of **pmempool_rm**(). +It is either 0 or the bitwise OR of one or more of the following flags: + ++ **PMEMPOOL_RM_FORCE** - Ignore all errors when removing part files from replicas. + ++ **PMEMPOOL_RM_POOLSET_LOCAL** - Also remove local pool set file. + +# RETURN VALUE # + +On success, **pmempool_rm**() returns 0. On error, it returns -1 and sets +*errno* accordingly. + +# SEE ALSO # + +**unlink**(3), **libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_sync.3.md b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_sync.3.md new file mode 100644 index 0000000000..1ea928fca8 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/libpmempool/pmempool_sync.3.md @@ -0,0 +1,135 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool_sync.3.html"] +title: "libpmempool | PMDK" +header: "pmempool API version 1.3" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2022, Intel Corporation) + +[comment]: <> (pmempool_sync.3 -- man page for pmempool sync and transform) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RETURN VALUE](#return-value)
+[ERRORS](#errors)
+[NOTES](#notes)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool_sync**(), **pmempool_transform**() - pool set synchronization and transformation + +# SYNOPSIS # + +```c +#include + +int pmempool_sync(const char *poolset_file, unsigned flags); (EXPERIMENTAL) +int pmempool_transform(const char *poolset_file_src, + const char *poolset_file_dst, unsigned flags); (EXPERIMENTAL) +``` + +# DESCRIPTION # + +The **pmempool_sync**() function synchronizes data between replicas within +a pool set. + +**pmempool_sync**() accepts two arguments: + +* *poolset_file* - a path to a pool set file, + +* *flags* - a combination of flags (ORed) which modify how synchronization +is performed. + +>NOTE: Only the pool set file used to create the pool should be used +for syncing the pool. + +>NOTE: The **pmempool_sync**() cannot do anything useful if there +are no replicas in the pool set. In such case, it fails with an error. + +>NOTE: Replication is only supported for **libpmemobj**(7) pools. + +The following flags are available: + +* **PMEMPOOL_SYNC_DRY_RUN** - do not apply changes, only check for viability of +synchronization. + +**pmempool_sync**() checks that the metadata of all replicas in +a pool set is consistent, i.e. all parts are healthy, and if any of them is +not, the corrupted or missing parts are recreated and filled with data from +one of the healthy replicas. + +If a pool set has the option *SINGLEHDR* (see **poolset**(5)), +the internal metadata of each replica is limited to the beginning of the first +part in the replica. If the option *NOHDRS* is used, replicas contain no +internal metadata. In both cases, only the missing parts or the ones which +cannot be opened are recreated with the **pmempool_sync**() function. + +**pmempool_transform**() modifies the internal structure of a pool set. +It supports the following operations: + +* adding one or more replicas, + +* removing one or more replicas, + +* adding or removing pool set options. + +Only one of the above operations can be performed at a time. + +**pmempool_transform**() accepts three arguments: + +* *poolset_file_src* - pathname of the pool *set* file for the source +pool set to be changed, + +* *poolset_file_dst* - pathname of the pool *set* file that defines the new +structure of the pool set, + +* *flags* - a combination of flags (ORed) which modify how synchronization +is performed. + +The following flags are available: + +* **PMEMPOOL_TRANSFORM_DRY_RUN** - do not apply changes, only check for viability of +transformation. + +>NOTE: The *transform* operation is only supported for **libpmemobj**(7) pools. + +# RETURN VALUE # + +**pmempool_sync**() and **pmempool_transform**() return 0 on success. +Otherwise, they return -1 and set *errno* appropriately. + +# ERRORS # + +**EINVAL** Invalid format of the input/output pool set file. + +**EINVAL** Unsupported *flags* value. + +**EINVAL** There is only master replica defined in the input pool set passed + to **pmempool_sync**(). + +**EINVAL** The source pool set passed to **pmempool_transform**() is not a + **libpmemobj** pool. + +**EINVAL** The input and output pool sets passed to **pmempool_transform**() + are identical. + +**EINVAL** Attempt to perform more than one transform operation at a time. + +# NOTES # + +The **pmempool_sync**() API is experimental and it may change in future +versions of the library. + +The **pmempool_transform**() API is experimental and it may change in future +versions of the library. + +# SEE ALSO # + +**libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmem_ctl/pmem_ctl.5.md b/content/pmdk/manpages/linux/v2.0/pmem_ctl/pmem_ctl.5.md new file mode 100644 index 0000000000..523963822b --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmem_ctl/pmem_ctl.5.md @@ -0,0 +1,126 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmem_ctl.5.html"] +title: "pmem_ctl | PMDK" +header: "pmem_ctl API version 1.4" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2018-2019, Intel Corporation) + +[comment]: <> (pmem_ctl.5 -- man page for CTL) + +[NAME](#name)
+[DESCRIPTION](#description)
+[CTL EXTERNAL CONFIGURATION](#ctl-external-configuration)
+[SEE ALSO](#see-also)
+ +# NAME # + +ctl - interface for examination and modification of the library's internal state. + +# DESCRIPTION # + +The CTL namespace is organized in a tree structure. Starting from the root, +each node can be either internal, containing other elements, or a leaf. +Internal nodes themselves can only contain other nodes and cannot be entry +points. There are two types of those nodes: *named* and *indexed*. Named nodes +have string identifiers. Indexed nodes represent an abstract array index and +have an associated string identifier. The index itself is provided by the user. +A collection of indexes present on the path of an entry point is provided to +the handler functions as name and index pairs. + +Entry points are the leaves of the CTL namespace structure. Each entry point +can read from the internal state, write to the internal state, +exec a function or a combination of these operations. + +The entry points are listed in the following format: + +name | r(ead)w(rite)x(ecute) | global/- | read argument type | write argument type | exec argument type | config argument type + +A description of **pmem_ctl** functions can be found on the +**libpmemobj_ctl_get**(3) manual page. + +# CTL EXTERNAL CONFIGURATION # + +In addition to direct function call, each write entry point can also be set +using two alternative methods. + +The first method is to load a configuration directly from the +**PMEMOBJ_CONF** environment variable. +A properly formatted ctl config string is a single-line +sequence of queries separated by ';': + +``` +query0;query1;...;queryN +``` + +A single query is constructed from the name of the ctl write entry point and +the argument, separated by '=': + +``` +entry_point=entry_point_argument +``` + +The entry point argument type is defined by the entry point itself, but there +are three predefined primitives: + + *) integer: represented by a sequence of [0-9] characters that form + a single number. + *) boolean: represented by a single character: y/n/Y/N/0/1, each + corresponds to true or false. If the argument contains any + trailing characters, they are ignored. + *) string: a simple sequence of characters. + +There are also complex argument types that are formed from the primitives +separated by a ',': + +``` +first_arg,second_arg +``` + +In summary, a full configuration sequence looks like this: + +``` +(first_entry_point)=(arguments, ...);...;(last_entry_point)=(arguments, ...); +``` + +As an example, to set both prefault at_open and at_create variables: +``` + +PMEMOBJ_CONF="prefault.at_open=1;prefault.at_create=1" +``` + +The second method of loading an external configuration is to set the +**PMEMOBJ_CONF_FILE** +environment variable to point to a file that contains +a sequence of ctl queries. The parsing rules are all the same, but the file +can also contain white-spaces and comments. + +To create a comment, simply use '#' anywhere in a line and everything +afterwards, until a new line, will be ignored. + +An example configuration file: + +``` +######################### +# My pmemobj configuration +######################### +# +# Global settings: +prefault. # modify the behavior of pre-faulting + at_open = 1; # prefault when the pool is opened + +prefault. + at_create = 0; # but don't prefault when it's created + +# Per-pool settings: +# ... + +``` +# SEE ALSO # + +**libpmemobj_ctl_get**(3) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-check.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-check.1.md new file mode 100644 index 0000000000..8cd5f21a7f --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-check.1.md @@ -0,0 +1,100 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-check.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-check.1 -- man page for pmempool-check) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-check** - check and repair persistent memory pool + +# SYNOPSIS # + +``` +$ pmempool check [] +``` + +# DESCRIPTION # + +The **pmempool** invoked with *check* command checks consistency of a given pool file. +If the pool file is consistent **pmempool** exits with 0 value. If the +pool file is not consistent non-zero error code is returned. + +In case of any errors, the proper message is printed. The verbosity level +may be increased using **-v** option. The output messages may be also suppressed using +**-q** option. + +It is possible to try to fix encountered problems using **-r** option. +In order to be sure this will not corrupt your data you can either create backup of the +pool file using **-b** option or just print what would be fixed +without modifying original pool using **-N** option. + +> NOTE: +Currently, checking the *pmemobj* pool is limited to pool header consistency +only and neither *repair* nor *advanced* options are supported. + +##### Available options: ##### + +`-r, --repair` + +Try to repair a pool file if possible. + +`-y, --yes` + +Answer yes on all questions. + +`-d, --dry-run` + +Don't execute, just show what would be done. Not supported on Device DAX. + +`-N, --no-exec` + +Deprecated alias for `dry-run`. + +`-b, --backup ` + +Create backup of a pool file before executing. Terminate if it is *not* +possible to create a backup file. This option requires **-r** option. + +`-a, --advanced` + +Perform advanced repairs. This option enables more aggressive steps in attempts +to repair a pool. This option requires `-r, --repair`. + +`-q, --quiet` + +Be quiet and don't print any messages. + +`-v, --verbose` + +Be more verbose. + +`-h, --help` + +Display help message and exit. + +# EXAMPLE # + +``` +$ pmempool check pool.obj +``` + +Check consistency of "pool.obj" pool file + +# SEE ALSO # + +**pmempool**(1), **libpmemobj**(7), **libpmempool**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-convert.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-convert.1.md new file mode 100644 index 0000000000..a889c2c16b --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-convert.1.md @@ -0,0 +1,27 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-convert.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-convert.1 -- man page for pmempool-convert) + +[NAME](#name)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-convert** - this is a wrapper around pmdk-convert tool. More information +can be found in **pmdk-convert**(1) man page. + +# SEE ALSO # + +**pmdk-convert**(1), **pmempool**(1), **libpmemobj**(7), **libpmempool**(7) +and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-create.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-create.1.md new file mode 100644 index 0000000000..93422f0818 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-create.1.md @@ -0,0 +1,119 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-create.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-create.1 -- man page for pmempool-create) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[EXAMPLE](#example)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-create** - create a persistent memory pool + +# SYNOPSIS # + +``` +$ pmempool create [] [] +``` + +# DESCRIPTION # + +The **pmempool** invoked with *create* command creates a pool file +of specified type. + +The only valid pool types is: **obj** which stands for *pmemobj* pool. +By default the pool file is created with *minimum* allowed size for specified +pool type. The minimum sizes for **obj** pool type is **PMEMOBJ_MIN_POOL**. +See **libpmemobj**(7) for details. + +In order to set custom size of pool use **-s** option, or use **-M** option +to create a pool of maximum available size on underlying file system. + +The *size* argument may be passed in format that permits only the upper-case +character for byte - B as specified in IEC 80000-13, IEEE 1541 and the +Metric Interchange Format. Standards accept SI units with obligatory +B - kB, MB, GB, ... which means multiplier by 1000 and IEC units with +optional "iB" - KiB, MiB, GiB, ..., K, M, G, ... - which means multiplier by 1024. + +##### Available options: ##### + +`-s, --size ` + +Size of pool file. + +`-M, --max-size` + +Set size of pool to available space of underlying file system. + +`-m, --mode ` + +Set permissions to (the default is 0664) when creating the files. +If the file already exist the permissions are not changed. + +`-i, --inherit ` + +Create a new pool of the same size and other properties as *\*. + +`-b, --clear-bad-blocks` + +Clear bad blocks in existing files. + +`-f, --force` + +Remove the pool before creating. + +`-v, --verbose` + +Increase verbosity level. + +`-h, --help` + +Display help message and exit. + +`-l, --layout ` + +Layout name of the **pmemobj** pool. By default when creating a pmem **obj** +pool, the layout name provided to the **libpmemobj** library is an empty string. +Please refer to **libpmemobj**(7) for details. + +# EXAMPLE # + +``` +$ pmempool create obj pool.obj +``` +Create a obj pool file of minimum allowed size + +``` +$ pmempool create obj -M pool.obj +``` + +Create a obj pool file of maximum allowed size + +``` +$ pmempool create --layout my_layout obj pool.obj +``` + +Create an obj pool file of minimum allowed size and layout "my_layout" + +``` +$ pmempool create --inherit=pool.obj new_pool.obj +``` + +Create a pool file based on pool.obj file + +# SEE ALSO # + +**pmempool**(1), **libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-dump.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-dump.1.md new file mode 100644 index 0000000000..f6c13bc3fa --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-dump.1.md @@ -0,0 +1,93 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-dump.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-dump.1 -- man page for pmempool-dump) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-dump** - dump user data from persistent memory pool + +# SYNOPSIS # + +``` +$ pmempool dump [] +``` + +# NOTE # + +> NOTICE: + +The **obj** pool type is not supported by the dump command. + +> NOTICE: + +The dump command is left only for backward compatibility. + +# DESCRIPTION # + +The **pmempool** invoked with *dump* command dumps user data from specified pool file. +The output format may be either binary or hexadecimal. + +By default the output format is hexadecimal. + +By default data is dumped to standard output. It is possible to dump data to other +file by specifying **-o** option. In this case data will be appended to this file. + +Using **-r** option you can specify number of data chunks using +special text format. See **RANGE** section for details. + +##### Available options: ##### + +`-b, --binary` + +Dump data in binary format. + +`-o, --output ` + +Name of output file. + +`-h, --help` + +Display help message and exit. + +# RANGE # + +Using **-r**, **--range** option it is possible to dump only a range of user data. +This section describes valid format of *\* string. + +You can specify multiple ranges separated by commas. + +`-` + +All blocks/bytes/data chunks from *\* to *\* will be dumped. + +`-` + +All blocks/bytes/data chunks up to *\* will be dumped. + +`-` + +All blocks/bytes/data chunks starting from *\* will be dumped. + +`` + +Only *\* block/byte/data chunk will be dumped. + +# SEE ALSO # + +**pmempool**(1), **libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-feature.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-feature.1.md new file mode 100644 index 0000000000..feaa11693a --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-feature.1.md @@ -0,0 +1,123 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-feature.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2018-2022, Intel Corporation) + +[comment]: <> (pmempool-feature.1 -- man page for pmempool-feature) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[COMPATIBILITY](#compatibility)
+[DISCLAIMER](#disclaimer)
+[EXAMPLE](#example)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-feature** - toggle or query pool set features + +# SYNOPSIS # + +``` +$ pmempool feature (-e|-d|-q feature-name) [options] +``` + +# DESCRIPTION # + +The **pmempool feature** command enables / disables or queries pool set features. + +Available pool *feature-names* are: + ++ **SINGLEHDR** - only the first part in each replica contains the pool part +internal metadata. This value can be used only with **-q**. It can not be +enabled or disabled. For details see **poolset**(5). + ++ **CHECKSUM_2K** - only the first 2KiB of pool part internal metadata +is checksummed. Other features may depend on this one to store additional metadata +in otherwise unused second 2KiB part of a header. +When **CHECKSUM_2K** is disabled whole 4KiB is checksummed. + ++ **SHUTDOWN_STATE** - enables additional check performed during +pool open which verifies pool consistency in the presence of dirty shutdown. +**CHECKSUM_2K** has to be enabled prior to **SHUTDOWN_STATE** +otherwise enabling **SHUTDOWN_STATE** will fail. + ++ **CHECK_BAD_BLOCKS** - enables checking bad blocks performed during opening +a pool and fixing bad blocks performed by pmempool-sync during syncing a pool. +Currently (Linux kernel v4.19, libndctl v62) checking and fixing bad blocks +require read access to the following resource files (containing physical +addresses) of NVDIMM devices which only root can read by default: + +``` +/sys/bus/nd/devices/ndbus*/region*/resource +/sys/bus/nd/devices/ndbus*/region*/dax*/resource +/sys/bus/nd/devices/ndbus*/region*/pfn*/resource +/sys/bus/nd/devices/ndbus*/region*/namespace*/resource +``` + +It is possible to use poolset as *file* argument. + +##### Available options: ##### + +`-h, --help` + +Print help message. + +`-v, --verbose` + +Increase verbosity level. + +`-e, --enable feature-name` + +Enable feature for pool set. + +`-d, --disable feature-name` + +Disable feature for pool set. + +`-q, --query feature-name` + +Print feature status. + +# COMPATIBILITY # + +Poolsets with features not defined in this document (e.g. enabled by the newer +software version) are not supported. + +# DISCLAIMER # + +```pmempool feature``` command is not fail safe. + +# EXAMPLE # + +``` +$ pmempool feature --enable CHECKSUM_2K pool.set +``` + +Enables POOL_FEAT_CKSUM_2K incompat feature flag. + +``` +$ pmempool feature --disable CHECKSUM_2K pool.set +``` + +Disables POOL_FEAT_CKSUM_2K incompat feature flag. + +``` +$ pmempool feature --query CHECKSUM_2K pool.set +0 +``` + +Prints POOL_FEAT_CKSUM_2K incompat feature flag value. + +# SEE ALSO # + +**poolset**(5) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-info.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-info.1.md new file mode 100644 index 0000000000..30851de9c5 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-info.1.md @@ -0,0 +1,295 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-info.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-info.1 -- man page for pmempool-info) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[RANGE](#range)
+[STATISTICS](#statistics)
+[EXAMPLE](#example)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-info** - show information about persistent memory pool + +# SYNOPSIS # + +``` +$ pmempool info [] +``` + +# DESCRIPTION # + +The **pmempool** invoked with *info* command analyzes an existing pool +created by **PMDK** libraries provided by **file** parameter. +The **file** can be either existing pool file, a part file or a poolset file. + +The main task of this command is to print all usable information from +pool headers and user data in human readable format. It automatically recognizes the pool +type by parsing and analyzing the pool header. The recognition +is done by checking the signature in the pool header. The main job of *info* command +is to present internal data structures as they are stored in file but *not* for checking +consistency. For this purpose there is the **pmempool-check**(1) command available. + +The **pmempool** with *info* command analyzes pool file as long as it is possible +regarding *correctness* of internal meta-data (correct offsets, sizes etc.). +If it is *not* possible to analyze the rest of the file, **pmempool** exits +with error code and prints appropriate error message. + +Currently there is lack of interprocess synchronization for pool files, +so the *info* command should be invoked off-line. Using **pmempool** on pool file which +may be modified by another process may lead to unexpected errors in pool file. + +**pmempool info** opens pool file in *read-only* mode so the file +will remain untouched after processing. + +The *info* command may collect and print basic statistics about data usage. +The statistics are specific to the type of pool. See **STATISTICS** section for details. + +Although the pool consistency is *not* checked by the *info* command, +it prints information about checksum errors and/or offsets errors. + +##### Available options: ##### + +By default the *info* command of **pmempool** prints information about the most important +internal data structures from pool. The particular set of headers and meta-data depend on +pool type. The pool type is recognized automatically and appropriate information is displayed +in human-readable format. + +To force processing specified file(s) as desired pool type use **-f** option +with appropriate name of pool type. The valid name of the pool type is **obj**. +This option may be useful when the pool header is corrupted and automatic +recognition of pool type fails. + +`-f, --force obj` + +Force parsing pool as specified pool type. + +>NOTE: +By default only pool headers and internal meta-data are displayed. +To display user data use **-d** option. Using **-r** option you can +specify number of objects using special text format. +See **RANGE** section for details. The range refers to +*object numbers* in case of pmem obj pool type. +See the **EXAMPLE** section for an example of usage of these options. + +`-d, --data` + +Dump user data in hexadecimal format. + +`-r, --range ` + +Range of objects/zone headers/chunk headers/lanes. +See **RANGE** section for details about range format. + +`-n, --human` + +Print sizes in human-readable format with appropriate units (e.g. 4k, 8M, 16G) + +`-x, --headers-hex` + +Print pool's internal data in mixed format which consists of hexadecimal dump of +header's data and parsed format displayed in human-readable format. This +allows one to see how data is stored in file. + +`-s, --stats` + +Print pool's statistics. See **STATISTICS** section for details. + +`-k, --bad-blocks=` + +Print bad blocks found in the pool. + +`-h, --help` + +Display help message and exit. + +>NOTE: +By default the *info* command displays all data blocks when **-d** options is used. +However it is possible to skip blocks marked with *zero* and/or *error* flags. +It is also possible to skip blocks which are *not* marked with any flag. Skipping +blocks has impact on blocks ranges (e.g. display 10 blocks marked with error flag +in the range from 0 to 10000) and statistics. + +`-z, --skip-zeros` + +Skip blocks marked with *zero* flag. + +`-e, --skip-error` + +Skip blocks marked with *error* flag. + +`-u, --skip-no-flag` + +Skip blocks *not* marked with any flag. + +By default the *info* command displays pool header and **pmemobj** pool descriptor. +In order to print information about other data structures one of the +following options may be used. + +`-l, --lanes []` + +Print information about lanes. If range is not specified all lanes are displayed. +The range can be specified using **-r** option right after the **-l** option. +See **RANGE** section for details about range format. + +`-R, --recovery` + +Print information about only those lanes which require recovery process. +This option requires **-l**, **--lanes** option. + +`-O, --object-store` + +Print information about all allocated objects. + +`-t, --types ` + +Print information about allocated objects only from specified range of type numbers. +If **-s**, **--stats** option is specified the objects statistics refer to objects from +specified range of type numbers. This option requires **-O**, **--object-store** or **-s**, +**--stats** options. See **RANGE** section for details about range format. + +`-E, --no-empty` + +Ignore empty lists of objects. This option requires **-O**, **--object-store** option. + +`-o, --root` + +Print information about a root object. + +`-A, --alloc-header` + +Print object's allocation header. This option requires **-O**, **--object-store** or **-l**, +**--lanes** or **-o**, **--root** options. + +`-a, --oob-header` + +Print object's out of band header. This option requires **-O**, **--object-store** or **-l**, +**--lanes** or **-o**, **--root** options. + +`-H, --heap` + +Print information about **pmemobj** heap. By default only a heap header is displayed. + +`-Z, --zones` + +If the **-H**, **--heap** option is used, print information about zones from specified range. +If the **-O**, **--object-store** option is used, print information about objects only +from specified range of zones. This option requires **-O**, **--object-store**, **-H**, **--heap** +or **-s**, **--stats** options. +The range can be specified using **-r** option right after the **-Z** option. +See **RANGE** section for details about range format. + +`-C, --chunks []` + +If the **-H, --heap** option is used, print information about chunks from specified range. +By default information about chunks of types *used* , *free* and *run* are displayed. +If the **-O, --object-store** option is used, print information about objects from +specified range of chunks within a zone. This option requires **-O, --object-store**, +**-H, --heap** or **-s, --stats** options. +The range can be specified using **-r** option right after the **-C** option. +See **RANGE** section for details about range format. + +`-T, --chunk-type used,free,run,footer` + +Print only specified type(s) of chunks. +The multiple types may be specified separated by comma. +This option requires **-H, --heap** and **-C, --chunks** options. + +`-b, --bitmap` + +Print bitmap of used blocks in chunks of type run. +This option requires **-H, --heap** and **-C, --chunks** options. + +`-p, --replica ` + +Print information from *\* replica. The 0 value means the master pool file. + +# RANGE # + +Using **-r, --range** option it is possible to dump only a range of user data. +This section describes valid format of *\* string. + +You can specify multiple ranges separated by commas. + +`-` + +All data chunks from *\* to *\* will be dumped. + +`-` + +All data chunks up to *\* will be dumped. + +`-` + +All data chunks starting from *\* will be dumped. + +`` + +Only *\* data chunk will be dumped. + +# STATISTICS # + +Below is the description of statistical measures for the *obj* pool type. + ++ **Object store** + + + **Number of objects** - Total number of objects and number of objects per type number. + + **Number of bytes** - Total number of bytes and number of bytes per type number. + ++ **Heap** + + + **Number of zones** - Total number of zones in the pool. + + **Number of used zones** - Number of used zones in the pool. + ++ **Zone** The zone's statistics are presented for each zone separately and the aggregated results from all zones. + + + **Number of chunks** - Total number of chunks in the zone and number of chunks of specified type. + + **Chunks size** - Total size of all chunks in the zone and sum of sizes of chunks of specified type. + ++ **Allocation classes** + + + **Units** - Total number of units of specified class. + + **Used units** - Number of used units of specified class. + + **Bytes** - Total number of bytes of specified class. + + **Used bytes** - Number of used bytes of specified class. + + **Total bytes** - Total number of bytes of all classes. + + **Total used bytes** - Total number of used bytes of all classes. + +# EXAMPLE # + +``` +$ pmempool info pool.obj +``` + +Parse and print information about pool.obj pool file. + +``` +$ pmempool info -d pool.obj +``` + +Print information and data in hexadecimal dump format for the pool.obj file. + +``` +$ pmempool info -d -r10-100 -eu pool.obj +``` + +Print information from the pool.obj file. Dump data chunks from 10 to 100, +skip blocks marked with error flag and not marked with any flag. + +# SEE ALSO # + +**pmempool**(1), **libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-rm.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-rm.1.md new file mode 100644 index 0000000000..60c8bd5b81 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-rm.1.md @@ -0,0 +1,96 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-rm.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-rm.1 -- man page for pmempool-rm) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[EXAMPLE](#example)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-rm** - remove a persistent memory pool + +# SYNOPSIS # + +``` +$ pmempool rm [] .. +``` + +# DESCRIPTION # + +The **pmempool rm** command removes each specified file. If the specified file +is a pool set file, all pool files (single-file pool or part files) are removed. +By default the **pmempool rm** does not remove pool set +files. All pool files are removed using **unlink**(3) call, +except the pools created on **device dax** which are zeroed instead. +If specified file does not exist the **pmempool rm** command terminates with an error code. +By default it prompts before removing *write-protected* files. +See the **EXAMPLE** section for an example usage of the *rm* command. + +##### Available options: ##### + +`-h, --help` + +Print help message + +`-v, --verbose` + +Be verbose and print all removing files. + +`-s, --only-pools` + +Remove only pool files and do not remove pool set files (default behaviour). + +`-a, --all` + +Remove all pool set files. + +`-l, --local` + +Remove local pool set files. + +`-f, --force` + +Remove all specified files, ignore nonexistent files, never prompt. + +`-i, --interactive` + +Prompt before removing every single file. + +# EXAMPLE # + +``` +$ pmempool rm pool1.obj pool2.obj +``` + +Remove specified pool files. + +``` +$ pmempool rm pool.set +``` + +Remove all pool files defined in the *pool.set* file. +Do not remove *pool.set* itself. + +``` +$ pmempool rm -a pool.set +``` + +Remove all pool files defined in the *pool.set* file and remove the *pool.set* itself. + +# SEE ALSO # + +**pmempool**(1), **libpmemobj**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-sync.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-sync.1.md new file mode 100644 index 0000000000..c8fc88b08c --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-sync.1.md @@ -0,0 +1,95 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-sync.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-sync.1 -- man page for pmempool-sync) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-sync** - Synchronize replicas or their parts within a pool set. + +# SYNOPSIS # + +``` +pmempool sync [options] +``` + +NOTE: Only the pool set file used to create the pool should be used +for syncing the pool. + +# DESCRIPTION # + +The **pmempool sync** command synchronizes data between replicas within +a pool set. It checks if metadata of all replicas in a pool set +are consistent, i.e. all parts are healthy, and if any of them is not, +the corrupted or missing parts are recreated and filled with data from one of +the healthy replicas. +Currently synchronizing data is allowed only for **pmemobj** pools (see +**libpmemobj**(7)). + +If a pool set has the option *SINGLEHDR* or *NOHDRS* +(see **poolset**(5)), **pmempool sync** command has limited capability +of checking its metadata. This is due to limited or no, respectively, internal +metadata at the beginning of pool set parts in every replica when either of the +options is used. In that cases, only missing parts or the ones which cannot +be opened are recreated. + +##### Available options: ##### + +`-b, --bad-blocks` + +Fix bad blocks - it causes creating or reading special recovery files. +When bad blocks are detected, special recovery files have to be created +in order to fix them safely. A separate recovery file is created for each part +of the pool. The recovery files are created in the same directory +where the poolset file is located using the following name pattern: +\ _r \ _p \ _badblocks.txt +These recovery files are automatically removed if the sync operation finishes +successfully. + +If the last sync operation was interrupted and not finished correctly +(e.g. the application crashed) and the bad blocks fixing procedure was +in progress, the bad block recovery files may be left over. In such case +bad blocks might have been cleared and zeroed, but the correct data from these +blocks was not recovered (not copied from a healthy replica), so the recovery +files MUST NOT be deleted manually, because it would cause a data loss. +Pmempool-sync should be run again with the '-b' option set. It will finish +the previously interrupted sync operation and copy correct data to zeroed +bad blocks using the left-over bad block recovery files (the bad blocks +will be read from the saved recovery files). Pmempool will delete the recovery +files automatically at the end of the sync operation. + +Using this option may have limitations depending on the operating system. +For details see description of the CHECK_BAD_BLOCKS feature +in **pmempool-feature**(1). + +`-d, --dry-run` + +Enable dry run mode. In this mode no changes are applied, only check for +viability of synchronization. + +`-v, --verbose` + +Increase verbosity level. + +`-h, --help` + +Display help message and exit. + +# SEE ALSO # + +**pmempool(1)**, **libpmempool(7)** and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-transform.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-transform.1.md new file mode 100644 index 0000000000..36f1c69478 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool-transform.1.md @@ -0,0 +1,138 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool-transform.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool-transform.1 -- man page for pmempool-transform) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[EXAMPLES](#examples)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool-transform** - Modify internal structure of a pool set. + +# SYNOPSIS # + +``` +pmempool transform [options] +``` + +# DESCRIPTION # + +The **pmempool transform** command modifies internal structure of a pool set +defined by the `poolset_file_src` file, according to a structure described in +the `poolset_file_dst` file. + +The following operations are supported: + +* adding replicas - one or more new replicas can be added and synchronized with +other replicas in the pool set, + +* removing replicas - one or more replicas can be removed from the pool set, + +* adding or removing pool set options. + +Only one of the above operations can be performed at a time. + +Currently adding and removing replicas are allowed only for **pmemobj** pools +(see **libpmemobj**(7)). + +The *poolset_file_src* argument provides the source pool set to be changed. + +The *poolset_file_dst* argument points to the target pool set. + +##### Available options: ##### + +`-d, --dry-run` + +Enable dry run mode. In this mode no changes are applied, only check for +viability of the operation is performed. + +`-v, --verbose` + +Increase verbosity level. + +`-h, --help` + +Display help message and exit. + +# EXAMPLES # + +##### Example 1. ##### + +Let files `/path/poolset_file_src` and `/path/poolset_file_dst` have the +following contents: + +``` +PMEMPOOLSET +20M /0/partfile1 +20M /0/partfile2 +25M /0/partfile3 +REPLICA +40M /1/partfile1 +20M /1/partfile2 +``` + +``` +PMEMPOOLSET +20M /0/partfile1 +20M /0/partfile2 +25M /0/partfile3 +REPLICA +40M /1/partfile1 +20M /1/partfile2 +REPLICA +50M /2/partfile1 +20M /2/partfile2 + +``` +Then, the command + +`pmempool transform /path/poolset_file_src /path/poolset_file_dst` + +adds a replica to the pool set. All other replicas remain unchanged and +the size of the pool remains 60M. + +##### Example 2. ##### + +Let files `/path/poolset_file_src` and `/path/poolset_file_dst` have the +following contents: + +``` +PMEMPOOLSET +20M /0/partfile1 +20M /0/partfile2 +25M /0/partfile3 +REPLICA +40M /1/partfile1 +20M /1/partfile2 +``` + +``` +PMEMPOOLSET +20M /0/partfile1 +20M /0/partfile2 +25M /0/partfile3 +``` +Then + +`pmempool_transform /path/poolset_file_src /path/poolset_file_dst` + +deletes the second replica from the pool set. The first replica remains +unchanged and the size of the pool is still 60M. + +# SEE ALSO # + +**pmempool(1)**, **libpmemobj(7)**, **libpmempool(7)** and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmempool/pmempool.1.md b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool.1.md new file mode 100644 index 0000000000..1331ad341a --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmempool/pmempool.1.md @@ -0,0 +1,128 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmempool.1.html"] +title: "pmempool | PMDK" +header: "pmem Tools version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2016-2023, Intel Corporation) + +[comment]: <> (pmempool.1 -- man page for pmempool) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[OPTIONS](#options)
+[COMMANDS](#commands)
+[DEBUGGING](#debugging)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmempool** - Persistent Memory Pool Management Tool + +# SYNOPSIS # + +``` +$ pmempool [--help] [--version] [] +``` + +# DESCRIPTION # + +The **pmempool** is a management tool for *Persistent Memory* pool files +created by **PMDK** libraries. + +The main purpose of **pmempool** is to provide a user with a set of utilities +for off-line analysis and manipulation of pools created by pmem libraries. +The pmempool is a generic command which consists of subcommands for specific +purposes. Some of subcommands are required to work *without* any impact +on processed pool, but some of them *may* create a new or modify an existing one. + +The **pmempool** may be useful for troubleshooting by system administrators +and for software developers who work on applications based on **PMDK**. +The latter may find these tools useful for testing and debugging purposes also. + +# OPTIONS # + +`-V, --version` + +Prints the version of **pmempool**. + +`-h, --help` + +Prints synopsis and list of commands. + +# COMMANDS # + +Currently there is a following set of commands available: + ++ **pmempool-info**(1) - +Prints information and statistics in human-readable format about specified pool. + ++ **pmempool-check**(1) - +Checks pool's consistency and repairs pool if it is not consistent. + ++ **pmempool-create**(1) - +Creates a pool of specified type with additional properties specific for this type of pool. + ++ **pmempool-dump**(1) - +Dumps usable data from pool in hexadecimal or binary format. + ++ **pmempool-rm**(1) - +Removes pool file or all pool files listed in pool set configuration file. + ++ **pmempool-convert**(1) - +Updates the pool to the latest available layout version. + ++ **pmempool-sync**(1) - +Synchronizes replicas within a poolset. + ++ **pmempool-transform**(1) - +Modifies internal structure of a poolset. + ++ **pmempool-feature**(1) - +Toggle or query a poolset features. + +In order to get more information about specific *command* you can use **pmempool help .** + +# DEBUGGING # + +The debug logs are available only in the debug version of the tool, +which is not provided by binary packages, but can be built from sources. +The **pmempool.static-debug** binary can be found in the 'src/tools/pmempool/' +subdirectory. + ++ **PMEMPOOL_TOOL_LOG_LEVEL** + +The value of **PMEMPOOL_TOOL_LOG_LEVEL** enables trace points in the debug version +of the tool, as follows: + ++ **0** - This is the default level when **PMEMPOOL_TOOL_LOG_LEVEL** is not set. +No log messages are emitted at this level. + ++ **1** - Additional details on any errors detected are logged (in addition +to returning the *errno*-based errors as usual). + ++ **2** - A trace of basic operations is logged. + ++ **3** - Enables a very verbose amount of function call tracing in the tool. + ++ **4** - Enables voluminous and fairly obscure tracing +information that is likely only useful to the **pmempool** developers. + +Unless **PMEMPOOL_TOOL_LOG_FILE** is set, debugging output is written to *stderr*. + ++ **PMEMPOOL_TOOL_LOG_FILE** + +Specifies the name of a file where all logging information should be written. +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 **PMEMPOOL_TOOL_LOG_FILE** is not set, output is written to *stderr*. + +# SEE ALSO # + +**libpmempool**(7) and **** diff --git a/content/pmdk/manpages/linux/v2.0/pmreorder/pmreorder.1.md b/content/pmdk/manpages/linux/v2.0/pmreorder/pmreorder.1.md new file mode 100644 index 0000000000..7beaee494c --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/pmreorder/pmreorder.1.md @@ -0,0 +1,424 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["pmreorder.1.html"] +title: "pmreorder | PMDK" +header: "pmreorder version 1.5" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2018-2022, Intel Corporation) + +[comment]: <> (pmreorder.1 -- man page for pmreorder) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[OPTIONS](#options)
+[ENGINES](#engines)
+[INSTRUMENTATION](#instrumentation)
+[PMEMCHECK STORE LOG](#pmemcheck-store-log)
+[ENVIRONMENT](#environment)
+[EXAMPLE](#example)
+[SEE ALSO](#see-also)
+ +# NAME # + +**pmreorder** - performs a persistent consistency check + using a store reordering mechanism + +# SYNOPSIS # + +``` +$ python pmreorder +``` + +# DESCRIPTION # + +The pmreorder tool is a collection of python scripts designed +to parse and replay operations logged by pmemcheck - +a persistent memory checking tool. + +Pmreorder performs the store reordering between persistent +memory barriers - a sequence of flush-fence operations. +It uses a consistency checking routine provided +in the command line options to check whether files are in a consistent state. +To help with this task, pmreorder sets an environmental variable +PMREORDER_MARKERS. Said variable contains a subset of markers +passed from the application, which is visible at the current state +of pmreordering. Individual markers are separated by vertical bar (‘|’). + +Example of how PMREORDER_MARKERS variable can be parsed in c++ using regex +based environment variable tokener: + +```cpp + auto env = std::getenv("ENV_PASS"); + std::string senv(env ? env : ""); + std::regex rgx("(\\w+)(\\||$)"); + for (std::sregex_iterator it(senv.begin(), senv.end(), rgx), it_end; + it != it_end; ++it) { + std::cout << (*it)[1].str() << std::endl; + } +``` + +Considering that logging, replaying and reordering of operations +are very time consuming, it is recommended to use as few stores as +possible in test workloads. + +# OPTIONS # + +`-h, --help` + +Prints synopsis and list of options. + +`-l, --logfile ` + +The pmemcheck log file to process. + +`-c, --checker ` + +Consistency checker type. + +`-p, --path ` + +Path to the consistency checker. +If the checker type is `prog` - given program **has to take a file name as +the last parameter** and the program has to return 0 for consistent cases +and 1 otherwise. +If the checker type is `lib` - `--name` parameter is required. + +`-n, --name ` + +The symbol name of the consistency checking function in the library. +The function **has to take a file name as the only parameter** and it +has to return 0 for consistent cases and 1 otherwise. +This parameter is required only if the checker type is `lib`. + +`-o, --output ` + +Set the logger output file. + +`-e, --output-level ` + +Set the output log level. + +`-r, --default-engine ` + +Set the initial reorder engine. Default value is `NoReorderNoCheck`. + +`-x, --extended-macros ` + +Assign an engine types to the defined marker. + +`-v, --version` + +Prints current version of pmreorder. + +# ENGINES # + +By default, the **NoReorderNoCheck** engine is used, +which means that for each set of stores, the tool +will pass-through all sequences of stores not reordered +and will not run consistency checker on them. + +To enable different types of the reorder engine and +begin proper reordering tests, a number of other +engines exist: + ++ **NoReorderDoCheck** - pass-through of unchanged operations. +Checks correctness of the stores as they were logged. +Useful for operations that do not require fail safety. + +``` +Example: + input: (a, b, c) + output: (a, b, c) +``` + ++ **ReorderAccumulative** - checks correctness on a growing +subset of the original sequence. + +``` +Example: + input: (a, b, c) + output: + () + (a) + (a, b) + (a, b, c) +``` + ++ **ReorderReverseAccumulative** - checks correctness on a reverted growing +subset of the original sequence. + +``` +Example: + input: (a, b, c) + output: + () + (c) + (c, b) + (c, b, a) +``` + ++ **ReorderPartial** - checks consistency on 3 randomly selected sequences +from a set of 1000 combinations of the original log, without repetitions. + +``` + Example: + input: (a, b, c) + output: + (b, c) + (b) + (a, b, c) +``` + ++ **ReorderFull** - for each set of stores generates and checks consistency +of all possible store permutations. +This might prove to be very computationally expensive for most workloads. +It can be useful for critical sections of code with limited number of stores. + +``` + Example: + input: (a, b, c) + output: + () + (a) + (b) + (c) + (a, b) + (a, c) + (b, a) + (b, c) + (c, a) + (c, b) + (a, b, c) + (a, c, b) + (b, a, c) + (b, c, a) + (c, a, b) + (c, b, a) +``` + +When the engine is passed with an `-r` option, it will be used +for each logged set of stores. +Additionally, the `-x` parameter can be used to switch engines +separately for any marked code sections. +For more details about `-x` extended macros functionality see section +INSTRUMENTATION below. + +# INSTRUMENTATION # + +The core of **pmreorder** is based on user-provided named markers. +Sections of code can be 'marked' depending on their importance, +and the degree of reordering can be customized by the use of various +provided engines. + +For this purpose, Valgrind's pmemcheck tool exposes a +generic marker macro: + ++ **VALGRIND_PMC_EMIT_LOG(value)** + +It emits log to *store_log* during pmemcheck processing. +*value* is a user-defined marker name. +For more details about pmemcheck execution see +PMEMCHECK STORE LOG section below. + +Example: +``` +main.c +. +. +. +VALGRIND_PMC_EMIT_LOG("PMREORDER_MEMSET_PERSIST.BEGIN"); + +pmem_memset_persist(...); + +VALGRIND_PMC_EMIT_LOG("PMREORDER_MEMSET_PERSIST.END"); +. +. +. +``` + +There are a few rules for macros creation: + ++ Valid macro can have any name, +but begin and end section have to match - +they are case sensitive. ++ Macro must have `.BEGIN` or `.END` suffix. ++ Macros can't be crossed. + +Defined markers can be assigned engines types and configured +through the **pmreorder** tool using the `-x` parameter. + +There are two ways to set macro options: + ++ Using command line interface in format: +``` +PMREORDER_MARKER_NAME1=Marker1,PMREORDER_MARKER_NAME2=Marker2 +``` + ++ Using configuration file in .json format: +``` +{ + "PMREORDER_MARKER_NAME1":"Marker1", + "PMREORDER_MARKER_NAME2":"Marker2" +} +``` + +For more details about available +engines types, see ENGINES section above. + +**libpmemobj**(7), **libpmem**(7) and **libpmem2**(7) also provide set of macros +that allow to change reordering engine on library or function level: + +`` + +Example of configuration on function level: +``` +{ + "pmemobj_open":"NoReorderNoCheck", + "pmemobj_memcpy_persist":"ReorderPartial" +} +``` + +Example of configuration on library level +(affecting all library functions): +``` +{ + "libpmemobj":"NoReorderNoCheck" +} +``` + +List of marked **libpmemobj**(7) API functions: + +``` +pmemobj_alloc +pmemobj_cancel +pmemobj_check +pmemobj_close +pmemobj_create +pmemobj_ctl_exec +pmemobj_ctl_set +pmemobj_free +pmemobj_list_insert +pmemobj_list_insert_new +pmemobj_list_move +pmemobj_list_remove +pmemobj_memcpy +pmemobj_memmove +pmemobj_memset +pmemobj_memcpy_persist +pmemobj_memset_persist +pmemobj_open +pmemobj_publish +pmemobj_realloc +pmemobj_reserve +pmemobj_root +pmemobj_root_construct +pmemobj_strdup +pmemobj_tx_abort +pmemobj_tx_add_range +pmemobj_tx_add_range_direct +pmemobj_tx_alloc +pmemobj_tx_commit +pmemobj_tx_free +pmemobj_tx_publish +pmemobj_tx_realloc +pmemobj_tx_strdup +pmemobj_tx_wcsdup +pmemobj_tx_xadd_range +pmemobj_tx_xadd_range_direct +pmemobj_tx_xalloc +pmemobj_tx_zalloc +pmemobj_tx_zrealloc +pmemobj_wcsdup +pmemobj_xalloc +pmemobj_xreserve +pmemobj_zalloc +pmemobj_zrealloc +``` + +List of marked **libpmem**(7) API functions: + +``` +pmem_memmove +pmem_memcpy +pmem_memset +pmem_memmove_nodrain +pmem_memcpy_nodrain +pmem_memset_nodrain +pmem_memmove_persist +pmem_memcpy_persist +pmem_memset_persist +``` + +List of **libpmem2**(7) API functions, which return marked functions: + +``` +pmem2_get_memcpy_fn (marker for the returned function has "pmem2_memmove" name) +pmem2_get_memmove_fn (marker for the returned function has "pmem2_memmove" name) +pmem2_get_memset_fn (marker for the returned function has "pmem2_memset" name) + +``` + +# PMEMCHECK STORE LOG # + +To generate *store_log* for **pmreorder** run pmemcheck +with additional parameters: + +``` +valgrind \ + --tool=pmemcheck \ + -q \ + --log-stores=yes \ + --print-summary=no \ + --log-file=store_log.log \ + --log-stores-stacktraces=yes \ + --log-stores-stacktraces-depth=2 \ + --expect-fence-after-clflush=yes \ + test_binary writer_parameter +``` + +For further details of pmemcheck parameters see +[pmemcheck documentation](https://pmem.io/valgrind/generated/pmc-manual.html) + +# ENVIRONMENT # + +By default all logging from PMDK libraries is disabled. +To enable API macros logging set environment variable: + ++ **PMREORDER_EMIT_LOG**=1 + +User defined markers passed from an application +are stored in the variable: + ++ **PMREORDER_MARKERS** + +# EXAMPLE # + +``` +python pmreorder.py \ + -l store_log.log \ + -r NoReorderDoCheck \ + -o pmreorder_out.log \ + -c prog \ + -x PMREORDER_MARKER_NAME=ReorderPartial \ + -p checker_binary checker_parameter(s) +``` + +Checker binary will be used to run consistency checks on +"store_log.log", output of pmemcheck tool. Any inconsistent +stores found during **pmreorder** analysis will be logged +to `pmreorder_out.log`. + +# SEE ALSO # + +**** diff --git a/content/pmdk/manpages/linux/v2.0/poolset/poolset.5.md b/content/pmdk/manpages/linux/v2.0/poolset/poolset.5.md new file mode 100644 index 0000000000..73d57f7681 --- /dev/null +++ b/content/pmdk/manpages/linux/v2.0/poolset/poolset.5.md @@ -0,0 +1,230 @@ +--- +draft: false +slider_enable: true +description: "" +disclaimer: "The contents of this web site and the associated GitHub repositories are BSD-licensed open source." +aliases: ["poolset.5.html"] +title: "poolset | PMDK" +header: "poolset API version 1.0" +--- + +[comment]: <> (SPDX-License-Identifier: BSD-3-Clause) +[comment]: <> (Copyright 2017-2022, Intel Corporation) + +[comment]: <> (poolset.5 -- man page that describes format of pool set file) + +[NAME](#name)
+[SYNOPSIS](#synopsis)
+[DESCRIPTION](#description)
+[REPLICAS](#replicas)
+[POOL SET OPTIONS](#pool-set-options)
+[NOTES](#notes)
+[SEE ALSO](#see-also)
+ +# NAME # + +poolset - persistent memory pool configuration file format + +# SYNOPSIS # + +```c +mypool.set +``` + +# DESCRIPTION # + +Depending on the configuration of the system, the available non-volatile +memory space may be divided into multiple memory devices. In such case, the +maximum size of the transactional object store could be limited by the capacity +of a single memory device. Therefore, **libpmemobj**(7) allows building object +stores spanning multiple memory devices by creation of persistent memory pools +consisting of multiple files, where each part of such a *pool set* may be stored +on a different pmem-aware filesystem. + +To improve reliability and eliminate single point of failure, **libpmemobj**(7) +also allows all the data written to a persistent memory pool to be copied +to local pool *replicas*, thereby providing backup for the +persistent memory pool by producing a *mirrored pool set*. In practice, +the pool replicas may be considered as binary copies of the "master" pool set. + +The *set* file for each type of pool is a plain text file. Lines in the file +are formatted as follows: + ++ The first line of the file must be the literal string "PMEMPOOLSET" + ++ The pool parts are specified, one per line, in the format: + + *size* *pathname* + ++ *Replica* sections, if any, start with the literal string "REPLICA". +See **REPLICAS**, below, for further details. + ++ Pool set options, if any, start with literal string *OPTION*. +See **POOL SET OPTIONS** below for details. + ++ Lines starting with "#" are considered comments and are ignored. + +The *size* must be compliant with the format specified in IEC 80000-13, IEEE 1541 +or the Metric Interchange Format. These standards accept SI units with +obligatory B - kB, MB, GB, ... (multiplier by 1000) suffixes, and IEC units +with optional "iB" - KiB, MiB, GiB, ..., K, M, G, ... - (multiplier by 1024) +suffixes. + +*pathname* must be an absolute pathname. + +The *pathname* of a part can point to a Device DAX. Device DAX is the +device-centric analogue of Filesystem DAX. It allows memory ranges to be +allocated and mapped without need of an intervening file system. + +Pools created on Device DAX have additional options and restrictions: + ++ The *size* may be set to "AUTO", in which case the size of the device will be +automatically resolved at pool creation time. + ++ To concatenate more than one Device DAX device into a single pool set, the +configured internal alignment of the devices must be 4KiB, unless the +*SINGLEHDR* or *NOHDRS* option is used in the pool set file. +See **POOL SET OPTIONS** below for details. + +Please see **ndctl-create-namespace**(1) for more information on Device DAX, +including how to configure desired alignment. + +The minimum file size of each part of the pool set +is defined as **PMEMOBJ_MIN_PART** in **\** + +The net pool size of the pool set is equal to: + +``` +net_pool_size = sum_over_all_parts(page_aligned_part_size - 4KiB) + 4KiB +``` +where +``` +page_aligned_part_size = part_size & ~(page_size - 1) +``` + +Note that page size is OS specific. For more information please see +**sysconf**(3). + +The minimum net pool size of a pool set +is defined as **PMEMOBJ_MIN_POOL** in **\** + +Here is an example "mypool.set" file: + +``` +PMEMPOOLSET +OPTION NOHDRS +100G /mountpoint0/myfile.part0 +200G /mountpoint1/myfile.part1 +400G /mountpoint2/myfile.part2 +``` + +The files in the set may be created by running one of the following commands. +To create a obj pool: + +``` +$ pmempool create obj mypool.set +``` + +# REPLICAS # + +Sections defining replica sets are optional. There may be multiple replica +sections. + +Replica sections begin with a line containing only the literal string +"REPLICA", followed by one or more pool part lines as described above. + +Here is an example "myobjpool.set" file with replicas: + +``` +PMEMPOOLSET +100G /mountpoint0/myfile.part0 +200G /mountpoint1/myfile.part1 +400G /mountpoint2/myfile.part2 + +# local replica +REPLICA +500G /mountpoint3/mymirror.part0 +200G /mountpoint4/mymirror.part1 +``` + +The files in the object pool set may be created by running the following command: + +``` +$ pmempool create --layout="mylayout" obj myobjpool.set +``` + +# POOL SET OPTIONS # + +Pool set options can appear anywhere after the line with *PMEMPOOLSET* string. +Pool set file can contain several pool set options. The following options are +supported: + ++ *SINGLEHDR* + +If the *SINGLEHDR* option is used, only the first part in each replica contains +the pool part internal metadata. In that case the effective size of a replica +is the sum of sizes of all its part files decreased once by 4096 bytes. + +When using the *SINGLEHDR* option, one can concatenate more than one +Device DAX devices with any internal alignments in one replica. + +Using the *SINGLEHDR* option has important implications for data +integrity checking and recoverability in case of a pool set damage. +See **pmempool_sync**() API for more information about pool set recovery. + +# DIRECTORIES # + +Providing a directory as a part's *pathname* allows the pool to dynamically +create files and consequently removes the user-imposed limit on the size +of the pool. + +The *size* argument of a part in a directory poolset becomes the size of the +address space reservation required for the pool. In other words, the size +argument is the maximum theoretical size of the mapping. This value can be +freely increased between instances of the application, but decreasing it below +the real required space will result in an error when attempting to open the +pool. + +The directory must NOT contain user created files with extension *.pmem*, +otherwise the behavior is undefined. If a file created by the library within +the directory is in any way altered (resized, renamed) the behavior is +undefined. + +A directory poolset must exclusively use directories to specify paths - +combining files and directories will result in an error. A single replica can +consist of one or more directories. If there are multiple directories, the +address space reservation is equal to the sum of the sizes. + +The order in which the files are created is unspecified, but the library will +try to maintain equal usage of the directories. + +By default pools grow in 128 megabyte increments. + +Only poolsets with the *SINGLEHDR* option can safely use directories. + +# NOTES # + +Creation of all the parts of the pool set and the associated replica sets can +be done with the **pmemobj_create**(3) function, or by using the **pmempool**(1) utility. + +Restoring data from a replica can be done by using the +**pmempool-sync**(1) command or the **pmempool_sync**() API from the +**libpmempool**(7) library. + +Modifications of a pool set file configuration can be done by using the +**pmempool-transform**(1) command or the **pmempool_transform**() API from the +**libpmempool**(7) library. + +When creating a pool set consisting of multiple files, or when creating +a replicated pool set, the *path* argument passed to **pmemobj_create**(3) +must point to the special *set* file that defines the pool layout and the location +of all the parts of the pool set. + +When opening a pool set consisting of multiple files, or when opening a +replicated pool set, the *path* argument passed to **pmemobj_open**(3) +must point to the same *set* file that was used for pool set creation. + +# SEE ALSO # + +**ndctl-create-namespace**(1), **pmemobj_create**(3), **sysconf**(3), +**libpmemobj**(7) and ****