.\" Automatically generated by Pandoc 2.2.1 .\" .TH "PMEM_IS_PMEM" "3" "2019-02-19" "PMDK - pmem API version 1.1" "PMDK Programmer's Manual" .hy .\" Copyright 2014-2019, Intel Corporation .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" * Neither the name of the copyright holder nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .SH NAME .PP \f[B]pmem_is_pmem\f[](), \f[B]pmem_map_file\f[](), \f[B]pmem_unmap\f[]() \- check persistency, create and delete mappings .SH SYNOPSIS .IP .nf \f[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); \f[] .fi .SH DESCRIPTION .PP Most pmem\-aware applications will take advantage of higher level libraries that alleviate the need for the application to call into \f[B]libpmem\f[] directly. Application developers that wish to access raw memory mapped persistence directly (via \f[B]mmap\f[](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. .PP The \f[B]pmem_is_pmem\f[]() function detects if the entire range [\f[I]addr\f[], \f[I]addr\f[]+\f[I]len\f[]) consists of persistent memory. Calling this function with a memory range that originates from a source different than \f[B]pmem_map_file()\f[] is undefined. The implementation of \f[B]pmem_is_pmem\f[]() 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 \f[B]pmem_is_pmem\f[]() once when a range of memory is first encountered, save the result, and use the saved result to determine whether \f[B]pmem_persist\f[](3) or \f[B]msync\f[](2) is appropriate for flushing changes to persistence. Calling \f[B]pmem_is_pmem\f[]() each time changes are flushed to persistence will not perform well. .PP The \f[B]pmem_map_file\f[]() function creates a new read/write mapping for a file. If \f[B]PMEM_FILE_CREATE\f[] is not specified in \f[I]flags\f[], the entire existing file \f[I]path\f[] is mapped, \f[I]len\f[] must be zero, and \f[I]mode\f[] is ignored. Otherwise, \f[I]path\f[] is opened or created as specified by \f[I]flags\f[] and \f[I]mode\f[], and \f[I]len\f[] must be non\-zero. \f[B]pmem_map_file\f[]() maps the file using \f[B]mmap\f[](2), but it also takes extra steps to make large page mappings more likely. .PP On success, \f[B]pmem_map_file\f[]() returns a pointer to the mapped area. If \f[I]mapped_lenp\f[] is not NULL, the length of the mapping is stored into *\f[I]mapped_lenp\f[]. If \f[I]is_pmemp\f[] is not NULL, a flag indicating whether the mapped file is actual pmem, or if \f[B]msync\f[]() must be used to flush writes for the mapped range, is stored into *\f[I]is_pmemp\f[]. .PP The \f[I]flags\f[] argument is 0 or the bitwise OR of one or more of the following file creation flags: .IP \[bu] 2 \f[B]PMEM_FILE_CREATE\f[] \- Create the file named \f[I]path\f[] if it does not exist. \f[I]len\f[] 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 \f[I]len.\f[] The new or existing file is then fully allocated to size \f[I]len\f[] using \f[B]posix_fallocate\f[](3). \f[I]mode\f[] specifies the mode to use in case a new file is created (see \f[B]creat\f[](2)). .PP The remaining flags modify the behavior of \f[B]pmem_map_file\f[]() when \f[B]PMEM_FILE_CREATE\f[] is specified. .IP \[bu] 2 \f[B]PMEM_FILE_EXCL\f[] \- If specified in conjunction with \f[B]PMEM_FILE_CREATE\f[], and \f[I]path\f[] already exists, then \f[B]pmem_map_file\f[]() will fail with \f[B]EEXIST\f[]. Otherwise, has the same meaning as \f[B]O_EXCL\f[] on \f[B]open\f[](2), which is generally undefined. .IP \[bu] 2 \f[B]PMEM_FILE_SPARSE\f[] \- When specified in conjunction with \f[B]PMEM_FILE_CREATE\f[], create a sparse (holey) file using \f[B]ftruncate\f[](2) rather than allocating it using \f[B]posix_fallocate\f[](3). Otherwise ignored. .IP \[bu] 2 \f[B]PMEM_FILE_TMPFILE\f[] \- Create a mapping for an unnamed temporary file. Must be specified with \f[B]PMEM_FILE_CREATE\f[]. \f[I]len\f[] must be non\-zero, \f[I]mode\f[] is ignored (the temporary file is always created with mode 0600), and \f[I]path\f[] must specify an existing directory name. If the underlying file system supports \f[B]O_TMPFILE\f[], the unnamed temporary file is created in the filesystem containing the directory \f[I]path\f[]; if \f[B]PMEM_FILE_EXCL\f[] is also specified, the temporary file may not subsequently be linked into the filesystem (see \f[B]open\f[](2)). Otherwise, the file is created in \f[I]path\f[] and immediately unlinked. .PP The \f[I]path\f[] can point to a Device DAX. In this case only the \f[B]PMEM_FILE_CREATE\f[] and \f[B]PMEM_FILE_SPARSE\f[] flags are valid, but they are both ignored. For Device DAX mappings, \f[I]len\f[] must be equal to either 0 or the exact size of the device. .PP To delete mappings created with \f[B]pmem_map_file\f[](), use \f[B]pmem_unmap\f[](). .PP The \f[B]pmem_unmap\f[]() 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 \f[I]addr\f[], where \f[I]addr\f[] must be a previously mapped region. \f[B]pmem_unmap\f[]() will delete the mappings using \f[B]munmap\f[](2). .SH RETURN VALUE .PP The \f[B]pmem_is_pmem\f[]() function returns true only if the entire range [\f[I]addr\f[], \f[I]addr\f[]+\f[I]len\f[]) consists of persistent memory. A true return from \f[B]pmem_is_pmem\f[]() means it is safe to use \f[B]pmem_persist\f[](3) and the related functions to make changes durable for that memory range. See also \f[B]CAVEATS\f[]. .PP On success, \f[B]pmem_map_file\f[]() returns a pointer to the memory\-mapped region and sets *\f[I]mapped_lenp\f[] and *\f[I]is_pmemp\f[] if they are not NULL. On error, it returns NULL, sets \f[I]errno\f[] appropriately, and does not modify *\f[I]mapped_lenp\f[] or *\f[I]is_pmemp\f[]. .PP On success, \f[B]pmem_unmap\f[]() returns 0. On error, it returns \-1 and sets \f[I]errno\f[] appropriately. .SH NOTES .PP On Linux, \f[B]pmem_is_pmem\f[]() returns true only if the entire range is mapped directly from Device DAX (/dev/daxX.Y) without an intervening file system. In the future, as file systems become available that support flushing with \f[B]pmem_persist\f[](3), \f[B]pmem_is_pmem\f[]() will return true as appropriate. .SH CAVEATS .PP The result of \f[B]pmem_is_pmem\f[]() query is only valid for the mappings created using \f[B]pmem_map_file\f[](). For other memory regions, in particular those created by a direct call to \f[B]mmap\f[](2), \f[B]pmem_is_pmem\f[]() always returns false, even if the queried range is entirely persistent memory. .PP Not all file systems support \f[B]posix_fallocate\f[](3). \f[B]pmem_map_file\f[]() will fail if \f[B]PMEM_FILE_CREATE\f[] is specified without \f[B]PMEM_FILE_SPARSE\f[] and the underlying file system does not support \f[B]posix_fallocate\f[](3). .SH SEE ALSO .PP \f[B]creat\f[](2), \f[B]ftruncate\f[](2), \f[B]mmap\f[](2), \f[B]msync\f[](2), \f[B]munmap\f[](2), \f[B]open\f[](2), \f[B]pmem_persist\f[](3), \f[B]posix_fallocate\f[](3), \f[B]libpmem\f[](7) and \f[B]\f[]