.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM_IS_PMEM" "3" "2022-08-25" "PMDK - pmem API version 1.1" "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2019, Intel Corporation
.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\ <libpmem.h>

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 if the entire range was
mapped directly from Device DAX (/dev/daxX.Y) without an intervening
file system, or \f[B]MAP_SYNC\f[] flag of \f[B]mmap(2)\f[] is supported
by the file system on Filesystem DAX.
.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]<https://pmem.io>\f[]