Merge pull request #5801 from osalyk/macros

doc:  remove unnecessary macros

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.

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
 **\<libpmem.h\>**, 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);
 	}
 

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.

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 <libpmem.h>
 
 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).
 

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.
 

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 <libpmem2.h>
 
-_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).

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).

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 <libpmem2.h>
 
-_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 #

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.

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 #