From 5202f6b2b09168764474d603946e82ad22424d99 Mon Sep 17 00:00:00 2001 From: Oksana Salyk Date: Fri, 14 Jul 2023 11:43:40 +0200 Subject: [PATCH] doc: remove unnecessary macros --- doc/README | 10 +- doc/libpmem/libpmem.7.md | 37 +++--- doc/libpmem/pmem_flush.3.md | 4 +- doc/libpmem/pmem_is_pmem.3.md | 26 ++--- doc/libpmem2/libpmem2.7.md | 12 +- doc/libpmem2/pmem2_errormsg.3.md | 10 +- doc/libpmem2/pmem2_map_new.3.md | 4 +- doc/libpmem2/pmem2_perror.3.md | 12 +- doc/libpmem2/pmem2_source_numa_node.3.md | 4 - doc/libpmem2/pmem2_source_size.3.md | 3 +- doc/libpmemobj/libpmemobj.7.md | 36 +++--- doc/libpmemobj/oid_is_null.3.md | 6 +- doc/libpmemobj/pmemobj_ctl_get.3.md | 25 ++-- doc/libpmemobj/pmemobj_open.3.md | 56 +++++---- doc/libpmempool/libpmempool.7.md | 50 ++++---- doc/libpmempool/pmempool_check_init.3.md | 106 ++++------------- doc/libpmempool/pmempool_feature_query.3.md | 28 +++-- doc/libpmempool/pmempool_rm.3.md | 14 +-- doc/libpmempool/pmempool_sync.3.md | 53 ++++----- doc/macros.man | 123 -------------------- doc/pmempool/pmempool-sync.1.md | 4 +- doc/pmempool/pmempool-transform.1.md | 15 +-- doc/poolset/poolset.5.md | 6 +- utils/md2man.sh | 20 +--- 24 files changed, 204 insertions(+), 460 deletions(-) delete mode 100644 doc/macros.man diff --git a/doc/README b/doc/README index 78d91be0479..0872e89bb54 100644 --- a/doc/README +++ b/doc/README @@ -10,9 +10,7 @@ links to examples and man pages. Developers new to PMDK are probably looking for libpmemobj. To generate web-based documentation or Linux man pages, you need to -have groff and pandoc installed. m4 macros are used in the document -sources to generate OS-specific variants of man pages and web-based -documentation. The macros are defined in macros.man. Processing is performed +have groff and pandoc installed. Processing is performed by the ../utils/md2man.sh script. All files in the *generated* directory are automatically generated and updated @@ -46,8 +44,8 @@ In addition, for testing purposes ../utils/md2man.sh will generate a preprocessed markdown file with the headers stripped off if the TESTOPTS variable is set. For example: - $ export TESTOPTS="-DWIN32 -UFREEBSD -UWEB" - $ ../utils/md2man.sh libpmemobj/libpmemobj.7.md x libpmemobj.7.win.md + $ export TESTOPTS="-DWEB" + $ ../utils/md2man.sh libpmemobj/libpmemobj.7.md x libpmemobj.7.web.md -will generate a version of the libpmemobj.7 man page for Windows in markdown +will generate a version of the libpmemobj.7 man page for web in markdown format. The resulting file may be viewed with a markdown-enabled browser. diff --git a/doc/libpmem/libpmem.7.md b/doc/libpmem/libpmem.7.md index 27c1c57d4d7..b64454422e7 100644 --- a/doc/libpmem/libpmem.7.md +++ b/doc/libpmem/libpmem.7.md @@ -35,20 +35,18 @@ header: "pmem API version 1.1" cc ... -lpmem ``` -_UNICODE() - ##### Library API versioning: ##### ```c -_UWFUNC(pmem_check_version, =q= +const char *pmem_check_version( unsigned major_required, - unsigned minor_required=e=) + unsigned minor_required); ``` ##### Error handling: ##### ```c -_UWFUNC(pmem_errormsg, void) +const char *pmem_errormsg(void); ``` ##### Other library functions: ##### @@ -98,15 +96,14 @@ resources associated with that thread might not be cleaned up properly. This section describes how the library API is versioned, allowing applications to work with an evolving API. -The _UW(pmem_check_version) function is used to determine whether the installed +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 = _U(pmem_check_version)(PMEM_MAJOR_VERSION, - PMEM_MINOR_VERSION); +reason = pmem_check_version(PMEM_MAJOR_VERSION, PMEM_MINOR_VERSION); if (reason != NULL) { /* version check failed, reason string tells you why */ } @@ -124,10 +121,10 @@ 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 _UW(pmem_check_version) is +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 _UW(pmem_check_version) must not be modified or +string returned by **pmem_check_version**() must not be modified or freed. # ENVIRONMENT # @@ -209,7 +206,7 @@ This variable is intended for use during library testing. + **PMEM_MMAP_HINT**=*val* This environment variable allows overriding -the hint address used by _UW(pmem_map_file). If set, it also disables +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 @@ -230,7 +227,7 @@ place the mapping. 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 _UW(pmem_errormsg). This function returns a pointer to a static buffer +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 @@ -248,11 +245,11 @@ 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 _DEBUGLIBPATH(), 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 _LDLIBPATH(). Debugging output is -controlled using the following environment variables. These variables have -no effect on the non-debug version of the library. +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** @@ -264,7 +261,7 @@ 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 _UW(pmem_errormsg). +may be retrieved using **pmem_errormsg**(). + **2** - A trace of basic operations is logged. @@ -320,9 +317,9 @@ main(int argc, char *argv[]) /* create a pmem file and memory map it */ - if ((pmemaddr = _U(pmem_map_file)(PATH, PMEM_LEN, PMEM_FILE_CREATE, + if ((pmemaddr = pmem_map_file(PATH, PMEM_LEN, PMEM_FILE_CREATE, 0666, &mapped_len, &is_pmem)) == NULL) { - perror("_U(pmem_map_file)"); + perror("pmem_map_file"); exit(1); } diff --git a/doc/libpmem/pmem_flush.3.md b/doc/libpmem/pmem_flush.3.md index 09d7728e862..61e813b8255 100644 --- a/doc/libpmem/pmem_flush.3.md +++ b/doc/libpmem/pmem_flush.3.md @@ -96,13 +96,11 @@ else /* ... */ ``` -_WINUX(,=q= >WARNING: -On Linux, **pmem_msync**() and **msync**(2) have no effect on memory ranges +**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. -=e=) The **pmem_flush**() and **pmem_drain**() functions provide partial versions of the **pmem_persist**() function. diff --git a/doc/libpmem/pmem_is_pmem.3.md b/doc/libpmem/pmem_is_pmem.3.md index b19b8abfccc..4fa8bc045c7 100644 --- a/doc/libpmem/pmem_is_pmem.3.md +++ b/doc/libpmem/pmem_is_pmem.3.md @@ -24,7 +24,7 @@ header: "pmem API version 1.1" # NAME # -**pmem_is_pmem**(), _UW(pmem_map_file), +**pmem_is_pmem**(), **pmem_map_file**(), **pmem_unmap**() - check persistency, create and delete mappings # SYNOPSIS # @@ -33,13 +33,11 @@ header: "pmem API version 1.1" #include int pmem_is_pmem(const void *addr, size_t len); -_UWFUNCR1(void, *pmem_map_file, *path, =q=size_t len, int flags, - mode_t mode, size_t *mapped_lenp, int *is_pmemp=e=) +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); ``` -_UNICODE() - # DESCRIPTION # Most pmem-aware applications will take advantage of higher level @@ -61,14 +59,14 @@ save the result, and use the saved result to determine whether persistence. Calling **pmem_is_pmem**() each time changes are flushed to persistence will not perform well. -The _UW(pmem_map_file) function creates a new read/write mapping for a +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. _UW(pmem_map_file) maps the file using **mmap**(2), but it +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, _UW(pmem_map_file) returns a pointer to the mapped area. If +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 @@ -85,11 +83,11 @@ following file creation flags: *mode* specifies the mode to use in case a new file is created (see **creat**(2)). -The remaining flags modify the behavior of _UW(pmem_map_file) when +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 _UW(pmem_map_file) will fail with **EEXIST**. + 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. @@ -112,7 +110,7 @@ The *path* can point to a Device DAX. In this case only the 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 _UW(pmem_map_file), use **pmem_unmap**(). +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 @@ -129,7 +127,7 @@ 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, _UW(pmem_map_file) returns a pointer to the memory-mapped region +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*. @@ -147,11 +145,11 @@ on Filesystem DAX. # CAVEATS # The result of **pmem_is_pmem**() query is only valid for the mappings -created using _UW(pmem_map_file). For other memory regions, in particular +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). _UW(pmem_map_file) will +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). diff --git a/doc/libpmem2/libpmem2.7.md b/doc/libpmem2/libpmem2.7.md index 0ad4de5bf15..8b705250c9c 100644 --- a/doc/libpmem2/libpmem2.7.md +++ b/doc/libpmem2/libpmem2.7.md @@ -233,11 +233,11 @@ 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 _DEBUGLIBPATH(), 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 _LDLIBPATH(). Debugging output is -controlled using the following environment variables. These variables have -no effect on the non-debug version of the library. +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** @@ -249,7 +249,7 @@ 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 _UW(pmem2_errormsg). +may be retrieved using **pmem2_errormsg**(). + **2** - A trace of basic operations is logged. diff --git a/doc/libpmem2/pmem2_errormsg.3.md b/doc/libpmem2/pmem2_errormsg.3.md index f17e10fe961..59d1f6a39b0 100644 --- a/doc/libpmem2/pmem2_errormsg.3.md +++ b/doc/libpmem2/pmem2_errormsg.3.md @@ -21,23 +21,21 @@ header: "pmem2 API version 1.0" # NAME # -_UW(pmem2_errormsg) - returns last error message +**pmem2_errormsg**() - returns last error message # SYNOPSIS # ```c #include -_UWFUNC(pmem2_errormsg, void) +const char *pmem2_errormsg(void); ``` -_UNICODE() - # 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 _UW(pmem2_errormsg). The error message buffer is thread-local; +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 @@ -47,7 +45,7 @@ Subsequent calls to other library functions may modify the previous message. # RETURN VALUE # -The _UW(pmem2_errormsg) function returns a pointer to a static buffer +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). diff --git a/doc/libpmem2/pmem2_map_new.3.md b/doc/libpmem2/pmem2_map_new.3.md index e014551c278..e140bf4fe48 100644 --- a/doc/libpmem2/pmem2_map_new.3.md +++ b/doc/libpmem2/pmem2_map_new.3.md @@ -92,11 +92,11 @@ the alignment required for specific *\*source*. Please see the alignment required for specific *\*source*. Please see **pmem2_source_alignment**(3). -* **PMEM2_E_SRC_DEVDAX_PRIVATE** - device DAX mapped with MAP_PRIVATE. (Linux only) +* **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). (Linux only) +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). diff --git a/doc/libpmem2/pmem2_perror.3.md b/doc/libpmem2/pmem2_perror.3.md index 25a2f56e560..6a43159bbf9 100644 --- a/doc/libpmem2/pmem2_perror.3.md +++ b/doc/libpmem2/pmem2_perror.3.md @@ -20,26 +20,24 @@ header: "pmem2 API version 1.0" # NAME # -_UW(pmem2_perror) - prints a descriptive error message to stderr +**pmem2_perror**() - prints a descriptive error message to stderr # SYNOPSIS # ```c #include -_UWFUNCR1(void, pmem2_perror, *format, ...) +void pmem2_perror(const char *format, ...); ``` -_UNICODE() - # DESCRIPTION # -The _UW(pmem2_perror) function produces a message on standard error stream describing +The **pmem2_perror**() function produces a message on standard error stream describing the last error encountered during library call. -_UW(pmem2_perror) takes a variable number of arguments. First, the argument string +**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 _UW(pmem2_errormsg), and a new-line. To see +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 # diff --git a/doc/libpmem2/pmem2_source_numa_node.3.md b/doc/libpmem2/pmem2_source_numa_node.3.md index e6c6847d62e..da3369c7642 100644 --- a/doc/libpmem2/pmem2_source_numa_node.3.md +++ b/doc/libpmem2/pmem2_source_numa_node.3.md @@ -49,12 +49,8 @@ If the function fails, the *\*numa_node* variable is left unmodified and a negat The **pmem2_source_numa_node**() can fail with the following errors: -On all systems: - * **PMEM2_E_NOSUPP** - source type or operating system not supported (see #caveats for details.) -on Linux: - * **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. diff --git a/doc/libpmem2/pmem2_source_size.3.md b/doc/libpmem2/pmem2_source_size.3.md index 16357162c97..3a163701009 100644 --- a/doc/libpmem2/pmem2_source_size.3.md +++ b/doc/libpmem2/pmem2_source_size.3.md @@ -39,8 +39,7 @@ 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 is a portable replacement for OS-specific APIs. -On Linux, it hides the quirkiness of Device DAX size detection. +This function hides the quirkiness of Device DAX size detection. # RETURN VALUE # diff --git a/doc/libpmemobj/libpmemobj.7.md b/doc/libpmemobj/libpmemobj.7.md index bfb282f19f5..3c089ae708c 100644 --- a/doc/libpmemobj/libpmemobj.7.md +++ b/doc/libpmemobj/libpmemobj.7.md @@ -31,16 +31,15 @@ header: "pmemobj API version 2.3" ```c #include -cc _WINUX(,-std=gnu99) ... -lpmemobj -lpmem +cc -std=gnu99 ... -lpmemobj -lpmem ``` -_UNICODE() ##### Library API versioning: ##### ```c -_UWFUNC(pmemobj_check_version, =q= +const char *pmemobj_check_version( unsigned major_required, - unsigned minor_required=e=) + unsigned minor_required); ``` ##### Managing library behavior: ##### @@ -56,7 +55,7 @@ void pmemobj_set_funcs( ##### Error handling: ##### ```c -_UWFUNC(pmemobj_errormsg, void) +const char *pmemobj_errormsg(void); ``` ##### Other library functions: ##### @@ -106,8 +105,8 @@ 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. -_WINUX(,=q=**libpmemobj** requires the **-std=gnu99** compilation flag to -build properly.=e=) +**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. @@ -122,15 +121,14 @@ below. This section describes how the library API is versioned, allowing applications to work with an evolving API. -The _UW(pmemobj_check_version) function is used to see if the installed +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 = _U(pmemobj_check_version)(PMEMOBJ_MAJOR_VERSION, - PMEMOBJ_MINOR_VERSION); +reason = pmemobj_check_version(PMEMOBJ_MAJOR_VERSION, PMEMOBJ_MINOR_VERSION); if (reason != NULL) { /* version check failed, reason string tells you why */ } @@ -147,9 +145,9 @@ interfaces described here are available in version 1.0 of the library. Interface 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, _UW(pmemobj_check_version) returns NULL. Otherwise, the return +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 _UW(pmemobj_check_version) must not be modified or freed. +string returned by **pmemobj_check_version**() must not be modified or freed. # MANAGING LIBRARY BEHAVIOR # @@ -168,7 +166,7 @@ desired limit. 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 _UW(pmemobj_errormsg). This function returns a pointer to a static buffer +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 @@ -186,11 +184,11 @@ 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 _DEBUGLIBPATH(), 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 _LDLIBPATH(). Debugging output is -controlled using the following environment variables. These variables have -no effect on the non-debug version of the library. +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** @@ -202,7 +200,7 @@ 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 _UW(pmemobj_errormsg). +The same information may be retrieved using **pmemobj_errormsg**(). + **2** - A trace of basic operations is logged. diff --git a/doc/libpmemobj/oid_is_null.3.md b/doc/libpmemobj/oid_is_null.3.md index 81ce7285fdb..c89e9b903fb 100644 --- a/doc/libpmemobj/oid_is_null.3.md +++ b/doc/libpmemobj/oid_is_null.3.md @@ -17,7 +17,7 @@ header: "pmemobj API version 2.3" [SYNOPSIS](#synopsis)
[DESCRIPTION](#description)
[RETURN VALUE](#return-value)
-_WINUX(,[NOTES](#notes)
) +[NOTES](#notes)
[SEE ALSO](#see-also)
# NAME # @@ -148,14 +148,12 @@ contains the object represented by *oid*. If the pool is not open or 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. -_WINUX(,=q= - # 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.=e=) +either with *\#define* or with the *\-D* option to the compiler. # EXAMPLES # diff --git a/doc/libpmemobj/pmemobj_ctl_get.3.md b/doc/libpmemobj/pmemobj_ctl_get.3.md index 1b92f0d8b4e..7f650ab7b71 100644 --- a/doc/libpmemobj/pmemobj_ctl_get.3.md +++ b/doc/libpmemobj/pmemobj_ctl_get.3.md @@ -22,9 +22,9 @@ header: "pmemobj API version 2.3" # NAME # -_UW(pmemobj_ctl_get), -_UW(pmemobj_ctl_set), -_UW(pmemobj_ctl_exec) +**pmemobj_ctl_get**(), +**pmemobj_ctl_set**(), +**pmemobj_ctl_exec**() - Query and modify libpmemobj internal behavior (EXPERIMENTAL) # SYNOPSIS # @@ -32,19 +32,14 @@ _UW(pmemobj_ctl_exec) ```c #include -_UWFUNCR2(int, pmemobj_ctl_get, PMEMobjpool *pop, *name, void *arg, - =q= (EXPERIMENTAL)=e=) -_UWFUNCR2(int, pmemobj_ctl_set, PMEMobjpool *pop, *name, void *arg, - =q= (EXPERIMENTAL)=e=) -_UWFUNCR2(int, pmemobj_ctl_exec, PMEMobjpool *pop, *name, void *arg, - =q= (EXPERIMENTAL)=e=) +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) ``` -_UNICODE() - # DESCRIPTION # -The _UW(pmemobj_ctl_get), _UW(pmemobj_ctl_set) and _UW(pmemobj_ctl_exec) +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. @@ -69,18 +64,18 @@ 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 _UW(pmemobj_create) function. +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 _UW(pmemobj_open) function. +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 _UW(pmemobj_create) function. See **pmempool_feature_query**(3) +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 diff --git a/doc/libpmemobj/pmemobj_open.3.md b/doc/libpmemobj/pmemobj_open.3.md index abc35b6fa50..31ffaf8a1b9 100644 --- a/doc/libpmemobj/pmemobj_open.3.md +++ b/doc/libpmemobj/pmemobj_open.3.md @@ -22,8 +22,8 @@ header: "pmemobj API version 2.3" # NAME # -_UW(pmemobj_open), _UW(pmemobj_create), -**pmemobj_close**(), _UW(pmemobj_check) +**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 @@ -32,24 +32,22 @@ _UW(pmemobj_open), _UW(pmemobj_create), ```c #include -_UWFUNCR1(PMEMobjpool, *pmemobj_open, *path, const char *layout) -_UWFUNCR1(PMEMobjpool, *pmemobj_create, *path, =q=const char *layout, - size_t poolsize, mode_t mode=e=) +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); -_UWFUNCR1(int, pmemobj_check, *path, const char *layout) +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); ``` -_UNICODE() - # DESCRIPTION # To use the pmem-resident transactional object store provided by **libpmemobj**(7), a *memory pool* must first be created -with the _UW(pmemobj_create) function described below. Existing pools -may be opened with the _UW(pmemobj_open) function. +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. @@ -63,19 +61,19 @@ pool appears to be persistent memory or a regular file (see the no need for applications to flush changes directly when using the object memory API provided by **libpmemobj**(7). -The _UW(pmemobj_create) function creates a transactional object store with the +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 _UW(pmemobj_open) is called. The layout name, including +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 _UW(pmemobj_create), and then specifying -*poolsize* as zero. In this case _UW(pmemobj_create) will take the pool size +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 @@ -92,12 +90,12 @@ 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 _UW(pmemobj_create); +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 _UW(pmemobj_create) must point to the special *set* file that defines +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 @@ -106,11 +104,11 @@ parts of the pool set. The *set* file is a plain text file, the structure of which is described in **poolset**(5). -The _UW(pmemobj_open) function opens an existing object store memory pool. -Similar to _UW(pmemobj_create), *path* must identify either an existing +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 _UW(pmemobj_create) when the pool was first created. This can +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. @@ -124,10 +122,10 @@ 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 -_UW(pmemobj_open) as described above. +**pmemobj_open**() as described above. -The _UW(pmemobj_check) function performs a consistency check of the file -indicated by *path*. _UW(pmemobj_check) opens the given *path* read-only so +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. @@ -139,29 +137,29 @@ pool, **pmemobj_get_user_data**() will return NULL. # RETURN VALUE # -The _UW(pmemobj_create) function returns a memory pool handle to be used with +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 _UW(pmemobj_open) function returns a memory pool handle to be used with +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, -_UW(pmemobj_open) returns NULL and sets *errno* appropriately. +**pmemobj_open**() returns NULL and sets *errno* appropriately. The **pmemobj_close**() function returns no value. -The _UW(pmemobj_check) function returns 1 if the memory pool is found to be -consistent. Any inconsistencies found will cause _UW(pmemobj_check) to +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). _UW(pmemobj_check) returns -1 and sets *errno* if it cannot +**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). _UW(pmemobj_create) will +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 # diff --git a/doc/libpmempool/libpmempool.7.md b/doc/libpmempool/libpmempool.7.md index 33dd83e4a4d..6bbfb7e5a11 100644 --- a/doc/libpmempool/libpmempool.7.md +++ b/doc/libpmempool/libpmempool.7.md @@ -30,23 +30,21 @@ header: "pmempool API version 1.3" ```c #include -cc _WINUX(,-std=gnu99) ... -lpmempool -lpmem +cc -std=gnu99 ... -lpmempool -lpmem ``` -_UNICODE() - ##### Library API versioning: ##### ```c -_UWFUNC(pmempool_check_version, =q= +const char *pmempool_check_version( unsigned major_required, - unsigned minor_required=e=) + unsigned minor_required); ``` ##### Error handling: ##### ```c -_UWFUNC(pmempool_errormsg, void) +const char *pmempool_errormsg(void); ``` ##### Other library functions: ##### @@ -87,22 +85,22 @@ 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. -_WINUX(,=q=**libpmempool** requires the **-std=gnu99** compilation flag to -build properly.=e=) +**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 _UW(pmempool_check_version) function is used to see if +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 = _U(pmempool_check_version)(PMEMPOOL_MAJOR_VERSION, +reason = pmempool_check_version(PMEMPOOL_MAJOR_VERSION, PMEMPOOL_MINOR_VERSION); if (reason != NULL) { /* version check failed, reason string tells you why */ @@ -122,17 +120,17 @@ 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 _UW(pmempool_check_version) +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 -_UW(pmempool_check_version) must not be modified or freed. +**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 _UW(pmempool_errormsg). This function returns a pointer to a static buffer +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 @@ -150,11 +148,11 @@ 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 _DEBUGLIBPATH(), 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 _LDLIBPATH(). Debugging output is -controlled using the following environment variables. These variables have -no effect on the non-debug version of the library. +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** @@ -166,7 +164,7 @@ 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 _UW(pmempool_errormsg). +may be retrieved using **pmempool_errormsg**(). + **2** - A trace of basic operations is logged. @@ -192,8 +190,8 @@ The program detects the type and checks consistency of given pool. If there are any issues detected, the pool is automatically repaired. ```c -#include _WINUX(,=q= -#include =e=) +#include +#include #include #include #include @@ -206,11 +204,11 @@ int main(int argc, char *argv[]) { PMEMpoolcheck *ppc; - struct _U(pmempool_check_status) *status; + struct pmempool_check_status *status; enum pmempool_check_result ret; /* arguments for check */ - struct _U(pmempool_check_args) args = { + struct pmempool_check_args args = { .path = PATH, .backup_path = NULL, .pool_type = PMEMPOOL_POOL_TYPE_DETECT, @@ -218,13 +216,13 @@ main(int argc, char *argv[]) }; /* initialize check context */ - if ((ppc = _U(pmempool_check_init)(&args, sizeof(args))) == NULL) { - perror("_U(pmempool_check_init)"); + 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 = _U(pmempool_check)(ppc)) != NULL) { + while ((status = pmempool_check(ppc)) != NULL) { switch (status->type) { case PMEMPOOL_CHECK_MSG_TYPE_ERROR: printf("%s\n", status->str.msg); diff --git a/doc/libpmempool/pmempool_check_init.3.md b/doc/libpmempool/pmempool_check_init.3.md index 2aabf8cfb85..5b0503d43ec 100644 --- a/doc/libpmempool/pmempool_check_init.3.md +++ b/doc/libpmempool/pmempool_check_init.3.md @@ -23,7 +23,7 @@ header: "pmempool API version 1.3" # NAME # -_UW(pmempool_check_init), _UW(pmempool_check), +**pmempool_check_init**(), **pmempool_check**(), **pmempool_check_end**() - checks pmempool health # SYNOPSIS # @@ -31,70 +31,34 @@ _UW(pmempool_check_init), _UW(pmempool_check), ```c #include -_UWFUNCR1UW(PMEMpoolcheck, *pmempool_check_init, struct pmempool_check_args, -*args,=q= - size_t args_size=e=) -_UWFUNCRUW(struct pmempool_check_status, *pmempool_check, PMEMpoolcheck *ppc) +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); ``` -_UNICODE() - # DESCRIPTION # To perform the checks provided by **libpmempool**, a *check context* -must first be initialized using the _UW(pmempool_check_init) +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, _UW(pmempool_check) must be called iteratively. +To execute checks, **pmempool_check**() must be called iteratively. Each call generates a new check status, represented by a -_UWS(pmempool_check_status) structure. Status messages are described +*struct pmempool_check_status* structure. Status messages are described later below. -When the checks are completed, _UW(pmempool_check) returns NULL. The check +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. -_UW(pmempool_check_init) initializes the check context. *args* describes +**pmempool_check_init**() initializes the check context. *args* describes parameters of the check context. *args_size* should be equal to the size of -the _UWS(pmempool_check_args). _UWS(pmempool_check_args) is defined as follows: - -_WINUX(=q= -```c -struct pmempool_check_argsU -{ - /* 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; -}; - -struct pmempool_check_argsW -{ - /* path to the pool to check */ - const wchar_t *path; - - /* optional backup path */ - const wchar_t *backup_path; - - /* type of the pool */ - enum pmempool_pool_type pool_type; +the *struct pmempool_check_args*. *struct pmempool_check_args* is defined as follows: - /* parameters */ - int flags; -}; -``` -=e=,=q= ```c struct pmempool_check_args { @@ -111,7 +75,6 @@ struct pmempool_check_args int flags; }; ``` -=e=) The *flags* argument accepts any combination of the following values (ORed): @@ -145,34 +108,10 @@ the same structure (the same number of parts with exactly the same size) as the Backup is supported only if the source *pool set* has no defined replicas. -The _UW(pmempool_check) function starts or resumes the check indicated by *ppc*. -When the next status is generated, the check is paused and _UW(pmempool_check) -returns a pointer to the _UWS(pmempool_check_status) structure: +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: -_WINUX(=q= -{ -```c -struct pmempool_check_statusU -{ - 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; -}; - -struct pmempool_check_statusW -{ - enum pmempool_check_msg_type type; /* type of the status */ - struct - { - const wchar_t *msg; /* status message string */ - const wchar_t *answer; /* answer to message if applicable */ - } str; -}; -``` -=e=,=q= ```c struct pmempool_check_status { @@ -184,7 +123,6 @@ struct pmempool_check_status } str; }; ``` -=e=) This structure can describe three types of statuses: @@ -197,21 +135,21 @@ This structure can describe three types of statuses: **PMEMPOOL_CHECK_ALWAYS_YES** flag was not set. It requires *answer* to be set to "yes" or "no" before continuing. -After calling _UW(pmempool_check) again, the previously provided -_UWS(pmempool_check_status) pointer must be considered invalid. +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 # -_UW(pmempool_check_init) returns an opaque handle of type *PMEMpoolcheck\**. +**pmempool_check_init**() returns an opaque handle of type *PMEMpoolcheck\**. If the provided parameters are invalid or the initialization process fails, -_UW(pmempool_check_init) returns NULL and sets *errno* appropriately. +**pmempool_check_init**() returns NULL and sets *errno* appropriately. -Each call to _UW(pmempool_check) returns a pointer to a -_UWS(pmempool_check_status) structure when a status is generated. When the -check completes, _UW(pmempool_check) returns NULL. +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 @@ -238,7 +176,7 @@ return one of the following values: This is an example of a *check context* initialization: ```c -struct _U(pmempool_check_args) args = +struct pmempool_check_args args = { .path = "/path/to/obj.pool", .backup_path = NULL, @@ -248,7 +186,7 @@ struct _U(pmempool_check_args) args = ``` ```c -PMEMpoolcheck *ppc = _U(pmempool_check_init)(&args, sizeof(args)); +PMEMpoolcheck *ppc = pmempool_check_init(&args, sizeof(args)); ``` The check will process a *pool* of type **PMEMPOOL_POOL_TYPE_OBJ** diff --git a/doc/libpmempool/pmempool_feature_query.3.md b/doc/libpmempool/pmempool_feature_query.3.md index ff194de9e43..4af1d7c1b09 100644 --- a/doc/libpmempool/pmempool_feature_query.3.md +++ b/doc/libpmempool/pmempool_feature_query.3.md @@ -24,23 +24,21 @@ set features) # NAME # -_UW(pmempool_feature_query), _UW(pmempool_feature_enable), -_UW(pmempool_feature_disable) - toggle or query pool set features +**pmempool_feature_query**(), **pmempool_feature_enable**(), +**pmempool_feature_disable**() - toggle or query pool set features # SYNOPSIS # ```c #include -_UWFUNCR1(int, pmempool_feature_query, *path, =q=enum pmempool_feature feature, unsigned flags=e=) +int pmempool_feature_query(const char *path, enum pmempool_feature feature, unsigned flags); -_UWFUNCR1(int, pmempool_feature_enable, *path, =q=enum pmempool_feature feature, unsigned flags=e=) +int pmempool_feature_enable(const char *path, enum pmempool_feature feature, unsigned flags); -_UWFUNCR1(int, pmempool_feature_disable, *path, =q=enum pmempool_feature feature, unsigned flags=e=) +int pmempool_feature_disable(const char *path, enum pmempool_feature feature, unsigned flags); ``` -_UNICODE() - # DESCRIPTION # The *feature* argument accepts following values: @@ -64,13 +62,13 @@ pool open which verifies pool consistency in the presence of dirty shutdown. during opening a pool and fixing bad blocks performed by pmempool-sync during syncing a pool. For details see **pmempool-feature**(1). -The _UW(pmempool_feature_query) function checks state of *feature* in the +The **pmempool_feature_query**() function checks state of *feature* in the pool set pointed by *path*. -The _UW(pmempool_feature_enable) function enables *feature* in the pool set +The **pmempool_feature_enable**() function enables *feature* in the pool set pointed by *path*. -The _UW(pmempool_feature_disable) function disables *feature* in the pool set +The **pmempool_feature_disable**() function disables *feature* in the pool set pointed by *path*. # COMPATIBILITY # @@ -80,18 +78,18 @@ software version) are not supported. # DISCLAIMER # -_UW(pmempool_feature_query), _UW(pmempool_feature_enable) and -_UW(pmempool_feature_disable) are not fail safe. +**pmempool_feature_query**(), **pmempool_feature_enable**() and +**pmempool_feature_disable**() are not fail safe. # RETURN VALUE # -On success, _UW(pmempool_feature_query) returns 0 if *feature* is disabled or +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, _UW(pmempool_feature_enable) returns 0. On error, it returns -1 +On success, **pmempool_feature_enable**() returns 0. On error, it returns -1 and sets *errno* accordingly. -On success, _UW(pmempool_feature_disable) returns 0. On error, it returns -1 +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 diff --git a/doc/libpmempool/pmempool_rm.3.md b/doc/libpmempool/pmempool_rm.3.md index 2c46fb3854f..e586344f725 100644 --- a/doc/libpmempool/pmempool_rm.3.md +++ b/doc/libpmempool/pmempool_rm.3.md @@ -21,26 +21,24 @@ header: "pmempool API version 1.3" # NAME # -_UW(pmempool_rm) - remove persistent memory pool +**pmempool_rm**() - remove persistent memory pool # SYNOPSIS # ```c #include -_UWFUNCR1(int, pmempool_rm, *path, int flags) +int pmempool_rm(const char *path, int flags); ``` -_UNICODE() - # DESCRIPTION # -The _UW(pmempool_rm) function removes the pool pointed to by *path*. The *path* +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, _UW(pmempool_rm) will remove all part files from replicas +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 _UW(pmempool_rm). +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. @@ -49,7 +47,7 @@ It is either 0 or the bitwise OR of one or more of the following flags: # RETURN VALUE # -On success, _UW(pmempool_rm) returns 0. On error, it returns -1 and sets +On success, **pmempool_rm**() returns 0. On error, it returns -1 and sets *errno* accordingly. # SEE ALSO # diff --git a/doc/libpmempool/pmempool_sync.3.md b/doc/libpmempool/pmempool_sync.3.md index da76eb70da4..1ea928fca87 100644 --- a/doc/libpmempool/pmempool_sync.3.md +++ b/doc/libpmempool/pmempool_sync.3.md @@ -23,27 +23,24 @@ header: "pmempool API version 1.3" # NAME # -_UW(pmempool_sync), _UW(pmempool_transform) - pool set synchronization and transformation +**pmempool_sync**(), **pmempool_transform**() - pool set synchronization and transformation # SYNOPSIS # ```c #include -_UWFUNCR1(int, pmempool_sync, *poolset_file,=q= - unsigned flags=e=, =q= (EXPERIMENTAL)=e=) -_UWFUNCR12(int, pmempool_transform, *poolset_file_src, - *poolset_file_dst, unsigned flags, =q= (EXPERIMENTAL)=e=) +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) ``` -_UNICODE() - # DESCRIPTION # -The _UW(pmempool_sync) function synchronizes data between replicas within +The **pmempool_sync**() function synchronizes data between replicas within a pool set. -_UW(pmempool_sync) accepts two arguments: +**pmempool_sync**() accepts two arguments: * *poolset_file* - a path to a pool set file, @@ -53,7 +50,7 @@ is performed. >NOTE: Only the pool set file used to create the pool should be used for syncing the pool. ->NOTE: The _UW(pmempool_sync) cannot do anything useful if there +>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. @@ -63,29 +60,29 @@ The following flags are available: * **PMEMPOOL_SYNC_DRY_RUN** - do not apply changes, only check for viability of synchronization. -_UW(pmempool_sync) checks that the metadata of all replicas in +**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. -_WINUX(,=q=If a pool set has the option *SINGLEHDR* (see **poolset**(5)), +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 _UW(pmempool_sync) function.=e=) +cannot be opened are recreated with the **pmempool_sync**() function. -_UW(pmempool_transform) modifies the internal structure of a pool set. +**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 _WINUX(.,=q=, +* removing one or more replicas, -* adding or removing pool set options.=e=) +* adding or removing pool set options. Only one of the above operations can be performed at a time. -_UW(pmempool_transform) accepts three arguments: +**pmempool_transform**() accepts three arguments: * *poolset_file_src* - pathname of the pool *set* file for the source pool set to be changed, @@ -101,21 +98,11 @@ The following flags are available: * **PMEMPOOL_TRANSFORM_DRY_RUN** - do not apply changes, only check for viability of transformation. -_WINUX(=q=When adding or deleting replicas, the two pool set files can differ only in the -definitions of replicas which are to be added or deleted. One cannot add and -remove replicas in the same step. Only one of these operations can be performed -at a time. Reordering replicas is not supported. -Also, to add a replica it is necessary for its effective size to match or -exceed the pool size. Otherwise the whole operation fails and no changes are -applied. The effective size of a replica is the sum of sizes of all its part -files decreased by 4096 bytes per each part file. The 4096 bytes of each part -file is utilized for storing internal metadata of the pool part files.=e=) - >NOTE: The *transform* operation is only supported for **libpmemobj**(7) pools. # RETURN VALUE # -_UW(pmempool_sync) and _UW(pmempool_transform) return 0 on success. +**pmempool_sync**() and **pmempool_transform**() return 0 on success. Otherwise, they return -1 and set *errno* appropriately. # ERRORS # @@ -125,22 +112,22 @@ Otherwise, they return -1 and set *errno* appropriately. **EINVAL** Unsupported *flags* value. **EINVAL** There is only master replica defined in the input pool set passed - to _UW(pmempool_sync). + to **pmempool_sync**(). -**EINVAL** The source pool set passed to _UW(pmempool_transform) is not a +**EINVAL** The source pool set passed to **pmempool_transform**() is not a **libpmemobj** pool. -**EINVAL** The input and output pool sets passed to _UW(pmempool_transform) +**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 _UW(pmempool_sync) API is experimental and it may change in future +The **pmempool_sync**() API is experimental and it may change in future versions of the library. -The _UW(pmempool_transform) API is experimental and it may change in future +The **pmempool_transform**() API is experimental and it may change in future versions of the library. # SEE ALSO # diff --git a/doc/macros.man b/doc/macros.man deleted file mode 100644 index 8f3668438a7..00000000000 --- a/doc/macros.man +++ /dev/null @@ -1,123 +0,0 @@ -# SPDX-License-Identifier: BSD-3-Clause -# Copyright 2017, Intel Corporation -# -# These macros are defined for the m4 preprocessor and are controlled by -# the FREEBSD, WIN32 and WEB variables. These MUST be explicitly defined or -# undefined on the m4 command line. -# -# This solution allows the maintenance of Windows, Linux and FreeBSD -# documentation in the same file. -# -# The macros are: -# -# _BSDWX(FreeBSD,WinLinux): -# Choose text based on FREEBSD. Both arguments are optional -# (although the comma must be present if FreeBSD is omitted). -# Bracket string with (=q=, =e=) if it contains commas. -# _DEBUGLIBPATH() -# Inserts pathnames for debug libraries depending on WIN32 and -# FREEBSD. -# _LDLIBPATH() -# Inserts suggested pathnames for LD_LIBRARY_PATH depending on -# WIN32 and FREEBSD. -# _MP(man_page_name, section): -# Include the man page section number if not building for WEB. -# _UNICODE(): -# Inserts a standard note regarding UNICODE support if WIN32. -# _U(func_name): -# Append "U" to func_name if WIN32. -# _UW(func_name): -# Emit **func_nameU**()/**func_nameW**() if WIN32. -# _UWFUNC(func_name, args): -# Define U and W prototypes of char/wchar_t *func_name if WIN32. -# Bracket args string with (=q=, =e=) if it is a comma-separated -# list. -# _UWFUNCR(ret_type, func_name, char_arg): -# Define U and W prototypes of ret_type func_name if WIN32. -# Single char/wchar_t argument is char_arg. -# _UWFUNCRUW(ret_type, func_name, args): -# Define U and W prototypes of ret_type[U/W] func_name if WIN32. -# Bracket args string with (=q=, =e=) if it is a comma-separated -# list. -# _UWFUNCR1(ret_type, func_name, char_arg, rest_of_args, comment): -# Define U and W prototypes of ret_type func_name if WIN32. -# First char/wchar_t argument is char_arg. Bracket rest_of_args -# string with (=q=, =e=) if it is a comma-separated list. -# Comment is added after prototype definition if present. -# _UWFUNCR12(ret_type, func_name, char_arg1, char_arg2, rest_of_args, -# comment): -# Define U and W prototypes of ret_type func_name if WIN32. -# Two char/wchar_t arguments are char_arg1-2. Bracket -# rest_of_args string with (=q=, =e=) if it is a comma-separated -# list. Comment is added after prototype definition if present. -# _UWFUNCR1UW(ret_type, func_name, arg1_type, arg1, rest_of_args): -# Define U and W prototypes of ret_type func_name, append [U/W] -# to arg1_type arg1. Bracket rest_of_args string with (=q=, =e=) -# if it is a comma-separated list. -# _UWFUNCR20(ret_type, func_name, arg1, char_arg): -# Define U and W prototypes of ret_type func_name if WIN32. -# Second char/wchar_t argument is char_arg. -# _UWFUNCR2(ret_type, func_name, arg1, char_arg, rest_of_args, comment): -# Define U and W prototypes of ret_type func_name if WIN32. -# Second char/wchar_t argument is char_arg. Bracket rest_of_args -# string with (=q=, =e=) if it is a comma-separated list. -# Comment is added after prototype definition if present. -# _UWS(struct_name): -# Emit *struct struct_nameU*/*struct struct_nameW* if WIN32. -# _WINUX(Windows,UX): -# Choose text based on WIN32. Both arguments are optional -# (although the comma must be present if Windows is omitted). -# Bracket string with (=q=, =e=) if it contains commas. - -changequote(=q=,=e=) -changecom() -define(_BSDWX, ifdef(=q=FREEBSD=e=,$1,$2)) -define(_DEBUGLIBPATH, ifdef(=q=WIN32=e=,**/pmdk/src/x64/Debug**, -ifdef(=q=FREEBSD=e=,**/usr/local/lib/pmdk_debug**, **/usr/lib/pmdk_debug**))) -define(_LDLIBPATH, ifdef(=q=WIN32=e=,**/pmdk/src/x64/Debug**, -ifdef(=q=FREEBSD=e=,**/usr/local/lib/pmdk_debug**, -=q==q==q=**/usr/lib/pmdk_debug** or **/usr/lib64/pmdk_debug**, as appropriate=e==e==e=))) -define(_MP, ifdef(=q=WEB=e=,$1,$1($2))) -define(_UNICODE, ifdef(=q=WIN32=e=,=q==q= ->NOTE: The PMDK API supports UNICODE. If the **PMDK_UTF8_API** macro is -defined, basic API functions are expanded to the UTF-8 API with postfix *U*. -Otherwise they are expanded to the UNICODE API with postfix *W*.=e==e=)) -define(_U, ifdef(=q=WIN32=e=,$1U,$1)) -define(_UW, ifdef(=q=WIN32=e=,**$1U**()/**$1W**(),**$1**())) -define(_UWFUNC, ifdef(=q=WIN32=e=, -const char *$1U($2); -const wchar_t *$1W($2);, -const char *$1($2);)) -define(_UWFUNCR, ifdef(=q=WIN32=e=, -$1 $2U(const char $3); -$1 $2W(const wchar_t $3);, -$1 $2(const char $3);)) -define(_UWFUNCRUW, ifdef(=q=WIN32=e=, -$1U $2U($3); -$1W $2W($3);, -$1 $2($3);)) -define(_UWFUNCR1, ifdef(=q=WIN32=e=, -$1 $2U(const char $3, $4);$5 -$1 $2W(const wchar_t $3, $4);$5, -$1 $2(const char $3, $4);$5)) -define(_UWFUNCR12, ifdef(=q=WIN32=e=, -$1 $2U(const char $3, - const char $4, $5);$6 -$1 $2W(const wchar_t $3, - const wchar_t $4, $5);$6, -$1 $2(const char $3, - const char $4, $5);$6)) -define(_UWFUNCR1UW, ifdef(=q=WIN32=e=, -$1 $2U($3U $4, $5); -$1 $2W($3W $4, $5);, -$1 $2($3 $4, $5);)) -define(_UWFUNCR20, ifdef(=q=WIN32=e=, -$1 $2U($3, const char $4); -$1 $2W($3, const wchar_t $4);, -$1 $2($3, const char $4);)) -define(_UWFUNCR2, ifdef(=q=WIN32=e=, -$1 $2U($3, const char $4, $5);$6 -$1 $2W($3, const wchar_t $4, $5);$6, -$1 $2($3, const char $4, $5);$6)) -define(_UWS, ifdef(=q=WIN32=e=,*struct $1U*/*struct $1W*,*struct $1*)) -define(_WINUX, ifdef(=q=WIN32=e=,$1,$2)) diff --git a/doc/pmempool/pmempool-sync.1.md b/doc/pmempool/pmempool-sync.1.md index 949696116f8..c8fc88b08cd 100644 --- a/doc/pmempool/pmempool-sync.1.md +++ b/doc/pmempool/pmempool-sync.1.md @@ -41,12 +41,12 @@ the healthy replicas. Currently synchronizing data is allowed only for **pmemobj** pools (see **libpmemobj**(7)). -_WINUX(,=q=If a pool set has the option *SINGLEHDR* or *NOHDRS* +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.=e=) +be opened are recreated. ##### Available options: ##### diff --git a/doc/pmempool/pmempool-transform.1.md b/doc/pmempool/pmempool-transform.1.md index ab0686e3f4b..36f1c694782 100644 --- a/doc/pmempool/pmempool-transform.1.md +++ b/doc/pmempool/pmempool-transform.1.md @@ -40,10 +40,9 @@ 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 -_WINUX(.,=q=, +* removing replicas - one or more replicas can be removed from the pool set, -* adding or removing pool set options.=e=) +* adding or removing pool set options. Only one of the above operations can be performed at a time. @@ -54,16 +53,6 @@ The *poolset_file_src* argument provides the source pool set to be changed. The *poolset_file_dst* argument points to the target pool set. -_WINUX(=q=When adding or deleting replicas, the two pool set files can differ only in the -definitions of replicas which are to be added or deleted. One cannot add and -remove replicas in the same step. Only one of these operations can be performed -at a time. Reordering replicas is not supported -Also, to add a replica it is necessary for its effective size to match or exceed -the pool size. Otherwise the whole operation fails and no changes are applied. -Effective size of a replica is the sum of sizes of all its part files decreased -by 4096 bytes per each part file. The 4096 bytes of each part file is -utilized for storing internal metadata of the pool part files.=e=) - ##### Available options: ##### `-d, --dry-run` diff --git a/doc/poolset/poolset.5.md b/doc/poolset/poolset.5.md index 72cb639cf62..73d57f76812 100644 --- a/doc/poolset/poolset.5.md +++ b/doc/poolset/poolset.5.md @@ -170,7 +170,7 @@ 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 _UW(pmempool_sync) API for more information about pool set recovery. +See **pmempool_sync**() API for more information about pool set recovery. # DIRECTORIES # @@ -208,11 +208,11 @@ 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 _UW(pmempool_sync) API from 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 _UW(pmempool_transform) API from 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 diff --git a/utils/md2man.sh b/utils/md2man.sh index 941bd3c964e..07be71a3e47 100755 --- a/utils/md2man.sh +++ b/utils/md2man.sh @@ -27,38 +27,26 @@ set -o pipefail filename=$1 template=$2 outfile=$3 -title=`sed -n 's/^title:\ _MP(*\([A-Za-z0-9_-]*\).*$/\1/p' $filename` +title=`sed -n 's/^title:\ *\([A-Za-z0-9_-]*\).*$/\1/p' $filename` section=`sed -n 's/^title:.*\([0-9]\))$/\1/p' $filename` version=`sed -n 's/^date:\ *\(.*\)$/\1/p' $filename` if [ "$TESTOPTS" != "" ]; then - m4 $TESTOPTS macros.man $filename | sed -n -e '/# NAME #/,$p' > $outfile + cat $filename | sed -n -e '/# NAME #/,$p' > $outfile else OPTS= -if [ "$WIN32" == 1 ]; then - OPTS="$OPTS -DWIN32" -else - OPTS="$OPTS -UWIN32" -fi - -if [ "$(uname -s)" == "FreeBSD" ]; then - OPTS="$OPTS -DFREEBSD" -else - OPTS="$OPTS -UFREEBSD" -fi - if [ "$WEB" == 1 ]; then OPTS="$OPTS -DWEB" mkdir -p "$(dirname $outfile)" - m4 $OPTS macros.man $filename | sed -n -e '/---/,$p' > $outfile + cat $filename | sed -n -e '/---/,$p' > $outfile else SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH:-$(date +%s)}" COPYRIGHT=$(grep -rwI "\[comment]: <> (Copyright" $filename |\ sed "s/\[comment\]: <> (\([^)]*\))/\1/") dt=$(date -u -d "@$SOURCE_DATE_EPOCH" +%F 2>/dev/null || date -u -r "$SOURCE_DATE_EPOCH" +%F 2>/dev/null || date -u +%F) - m4 $OPTS macros.man $filename | sed -n -e '/# NAME #/,$p' |\ + cat $filename | sed -n -e '/# NAME #/,$p' |\ pandoc -s -t man -o $outfile --template=$template \ -V title=$title -V section=$section \ -V date="$dt" -V version="$version" \