Provided by: libpmem-dev_1.13.1-1.1ubuntu2_amd64 bug

NAME

       pmem_is_pmem(),  pmem_map_file(),  pmem_unmap()  -  check  persistency,  create and delete
       mappings

SYNOPSIS

              #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);

DESCRIPTION

       Most pmem-aware applications will take advantage of higher level libraries that  alleviate
       the  need  for the application to call into libpmem directly.  Application developers that
       wish to access raw memory mapped persistence directly (via mmap(2)) and that wish to  take
       on the responsibility for flushing stores to persistence will find the functions described
       in this section to be the most commonly used.

       The pmem_is_pmem() function detects if the  entire  range  [addr,  addr+len)  consists  of
       persistent  memory.   Calling  this  function  with  a memory range that originates from a
       source different than pmem_map_file() is undefined.  The implementation of  pmem_is_pmem()
       requires  a  non-trivial  amount  of  work  to  determine  if  the given range is entirely
       persistent memory.  For this reason, it is better to call pmem_is_pmem() once when a range
       of  memory  is  first  encountered, save the result, and use the saved result to determine
       whether pmem_persist(3) or msync(2) is appropriate for flushing  changes  to  persistence.
       Calling pmem_is_pmem() each time changes are flushed to persistence will not perform well.

       The   pmem_map_file()   function  creates  a  new  read/write  mapping  for  a  file.   If
       PMEM_FILE_CREATE is not specified in flags, the entire existing file path is  mapped,  len
       must  be  zero, and mode is ignored.  Otherwise, path is opened or created as specified by
       flags and mode, and len must be non-zero.  pmem_map_file() maps the  file  using  mmap(2),
       but it also takes extra steps to make large page mappings more likely.

       On  success,  pmem_map_file() returns a pointer to the mapped area.  If mapped_lenp is not
       NULL, the length of the mapping is stored into *mapped_lenp.  If is_pmemp is not  NULL,  a
       flag  indicating  whether  the  mapped  file is actual pmem, or if msync() must be used to
       flush writes for the mapped range, is stored into *is_pmemp.

       The flags argument is 0 or the bitwise OR of one or more of the  following  file  creation
       flags:

       • PMEM_FILE_CREATE  -  Create  the file named path if it does not exist.  len must be non-
         zero and specifies the size of the file to be created.  If the file already  exists,  it
         will  be  extended or truncated to len. The new or existing file is then fully allocated
         to size len using posix_fallocate(3).  mode specifies the mode to use in case a new file
         is created (see creat(2)).

       The  remaining  flags  modify  the  behavior  of  pmem_map_file() when PMEM_FILE_CREATE is
       specified.

       • PMEM_FILE_EXCL - If specified in conjunction with  PMEM_FILE_CREATE,  and  path  already
         exists,  then pmem_map_file() will fail with EEXIST.  Otherwise, has the same meaning as
         O_EXCL on open(2), which is generally undefined.

       • PMEM_FILE_SPARSE - When specified in conjunction with PMEM_FILE_CREATE, create a  sparse
         (holey)  file  using  ftruncate(2)  rather  than allocating it using posix_fallocate(3).
         Otherwise ignored.

       • PMEM_FILE_TMPFILE - Create a mapping for an unnamed temporary file.  Must  be  specified
         with  PMEM_FILE_CREATE.   len  must  be non-zero, mode is ignored (the temporary file is
         always created with mode 0600), and path must specify an existing  directory  name.   If
         the  underlying file system supports O_TMPFILE, the unnamed temporary file is created in
         the filesystem containing the directory path; if PMEM_FILE_EXCL is also  specified,  the
         temporary  file  may  not  subsequently  be  linked  into  the filesystem (see open(2)).
         Otherwise, the file is created in path and immediately unlinked.

       The path can point  to  a  Device  DAX.   In  this  case  only  the  PMEM_FILE_CREATE  and
       PMEM_FILE_SPARSE flags are valid, but they are both ignored.  For Device DAX mappings, len
       must be equal to either 0 or the exact size of the device.

       To delete mappings created with pmem_map_file(), use pmem_unmap().

       The pmem_unmap() function deletes all the mappings for the specified  address  range,  and
       causes  further  references  to  addresses  within  the  range  to generate invalid memory
       references.  It will use the address specified by the parameter addr, where addr must be a
       previously mapped region.  pmem_unmap() will delete the mappings using munmap(2).

RETURN VALUE

       The  pmem_is_pmem()  function  returns  true  only  if  the  entire range [addr, addr+len)
       consists of persistent memory.  A true return from pmem_is_pmem() means it is safe to  use
       pmem_persist(3)  and  the related functions to make changes durable for that memory range.
       See also CAVEATS.

       On success, pmem_map_file() returns  a  pointer  to  the  memory-mapped  region  and  sets
       *mapped_lenp  and  *is_pmemp  if they are not NULL.  On error, it returns NULL, sets errno
       appropriately, and does not modify *mapped_lenp or *is_pmemp.

       On success, pmem_unmap() returns 0.  On error, it returns -1 and sets errno appropriately.

NOTES

       On Linux, pmem_is_pmem() returns true if the entire range was mapped directly from  Device
       DAX  (/dev/daxX.Y)  without  an  intervening  file  system, or MAP_SYNC flag of mmap(2) is
       supported by the file system on Filesystem DAX.

CAVEATS

       The result  of  pmem_is_pmem()  query  is  only  valid  for  the  mappings  created  using
       pmem_map_file().   For  other memory regions, in particular those created by a direct call
       to mmap(2), pmem_is_pmem() always returns false, even if the  queried  range  is  entirely
       persistent memory.

       Not   all   file   systems  support  posix_fallocate(3).   pmem_map_file()  will  fail  if
       PMEM_FILE_CREATE is specified without PMEM_FILE_SPARSE and the underlying file system does
       not support posix_fallocate(3).

SEE ALSO

       creat(2),   ftruncate(2),   mmap(2),   msync(2),   munmap(2),   open(2),  pmem_persist(3),
       posix_fallocate(3), libpmem(7) and <https://pmem.io>