pmem_is_pmem(3)

1PMEM_IS_PMEM(3)            PMDK Programmer's Manual            PMEM_IS_PMEM(3)
2
3
4

NAME

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

SYNOPSIS

10              #include <libpmem.h>
11
12              int pmem_is_pmem(const void *addr, size_t len);
13              void *pmem_map_file(const char *path, size_t len, int flags,
14                  mode_t mode, size_t *mapped_lenp, int *is_pmemp);
15              int pmem_unmap(void *addr, size_t len);
16

DESCRIPTION

18       Most pmem-aware applications will take advantage of  higher  level  li‐
19       braries  that alleviate the need for the application to call into libp‐
20       mem directly.  Application developers that wish to  access  raw  memory
21       mapped  persistence directly (via mmap(2)) and that wish to take on the
22       responsibility for flushing stores to persistence will find  the  func‐
23       tions described in this section to be the most commonly used.
24
25       The  pmem_is_pmem()  function  detects  if  the entire range [addr, ad‐
26       dr+len)  consists  of  persistent  memory.    The   implementation   of
27       pmem_is_pmem()  requires  a  non-trivial amount of work to determine if
28       the given range is entirely persistent memory.  For this reason, it  is
29       better  to call pmem_is_pmem() once when a range of memory is first en‐
30       countered, save the result, and  use  the  saved  result  to  determine
31       whether pmem_persist(3) or msync(2) is appropriate for flushing changes
32       to persistence.  Calling pmem_is_pmem() each time changes  are  flushed
33       to persistence will not perform well.
34
35       The  pmem_map_file()  function  creates  a new read/write mapping for a
36       file.  If PMEM_FILE_CREATE is not specified in flags, the entire exist‐
37       ing file path is mapped, len must be zero, and mode is ignored.  Other‐
38       wise, path is opened or created as specified by flags and mode, and len
39       must  be non-zero.  pmem_map_file() maps the file using mmap(2), but it
40       also takes extra steps to make large page mappings more likely.
41
42       On success, pmem_map_file() returns a pointer to the mapped  area.   If
43       mapped_lenp  is  not  NULL,  the  length  of the mapping is stored into
44       *mapped_lenp.  If is_pmemp is not NULL, a flag indicating  whether  the
45       mapped  file is actual pmem, or if msync() must be used to flush writes
46       for the mapped range, is stored into *is_pmemp.
47
48       The flags argument is 0 or the bitwise OR of one or more of the follow‐
49       ing file creation flags:
50
51       · PMEM_FILE_CREATE  -  Create the file named path if it does not exist.
52         len must be non-zero and specifies the size of the file to be  creat‐
53         ed.   If the file already exists, it will be extended or truncated to
54         len. The new or existing file is then fully allocated to size len us‐
55         ing posix_fallocate(3).  mode specifies the mode to use in case a new
56         file is created (see creat(2)).
57
58       The  remaining  flags  modify  the  behavior  of  pmem_map_file()  when
59       PMEM_FILE_CREATE is specified.
60
61       · PMEM_FILE_EXCL  -  If specified in conjunction with PMEM_FILE_CREATE,
62         and path already exists, then pmem_map_file() will fail with  EEXIST.
63         Otherwise, has the same meaning as O_EXCL on open(2), which is gener‐
64         ally undefined.
65
66       · PMEM_FILE_SPARSE - When specified in conjunction with  PMEM_FILE_CRE‐
67         ATE,  create a sparse (holey) file using ftruncate(2) rather than al‐
68         locating it using posix_fallocate(3).  Otherwise ignored.
69
70       · PMEM_FILE_TMPFILE - Create a mapping for an unnamed  temporary  file.
71         Must  be specified with PMEM_FILE_CREATE.  len must be non-zero, mode
72         is ignored (the temporary file is always created with mode 0600), and
73         path must specify an existing directory name.  If the underlying file
74         system supports O_TMPFILE, the unnamed temporary file is  created  in
75         the  filesystem  containing  the directory path; if PMEM_FILE_EXCL is
76         also specified, the temporary file may not subsequently be linked in‐
77         to  the  filesystem (see open(2)).  Otherwise, the file is created in
78         path and immediately unlinked.
79
80       The  path  can  point  to  a  Device  DAX.   In  this  case  only   the
81       PMEM_FILE_CREATE  and  PMEM_FILE_SPARSE  flags  are valid, but they are
82       both ignored.  For Device DAX mappings, len must be equal to  either  0
83       or the exact size of the device.
84
85       To delete mappings created with pmem_map_file(), use pmem_unmap().
86
87       The  pmem_unmap()  function  deletes all the mappings for the specified
88       address range, and causes further references to  addresses  within  the
89       range  to  generate invalid memory references.  It will use the address
90       specified by the parameter addr, where addr must be a previously mapped
91       region.  pmem_unmap() will delete the mappings using munmap(2).
92

RETURN VALUE

94       The  pmem_is_pmem() function returns true only if the entire range [ad‐
95       dr, addr+len) consists  of  persistent  memory.   A  true  return  from
96       pmem_is_pmem()  means it is safe to use pmem_persist(3) and the related
97       functions to make changes durable for  that  memory  range.   See  also
98       CAVEATS.
99
100       On  success, pmem_map_file() returns a pointer to the memory-mapped re‐
101       gion and sets *mapped_lenp and *is_pmemp if they are not NULL.  On  er‐
102       ror,  it  returns  NULL,  sets errno appropriately, and does not modify
103       *mapped_lenp or *is_pmemp.
104
105       On success, pmem_unmap() returns 0.  On error, it returns -1  and  sets
106       errno appropriately.
107

NOTES

109       On  Linux,  pmem_is_pmem()  returns  true  only  if the entire range is
110       mapped directly from Device DAX (/dev/daxX.Y)  without  an  intervening
111       file system.  In the future, as file systems become available that sup‐
112       port flushing with pmem_persist(3), pmem_is_pmem() will return true  as
113       appropriate.
114

CAVEATS

116       The  result of pmem_is_pmem() query is only valid for the mappings cre‐
117       ated using pmem_map_file().  For other memory  regions,  in  particular
118       those  created  by  a direct call to mmap(2), pmem_is_pmem() always re‐
119       turns false, even if the queried range is entirely persistent memory.
120
121       Not all file systems support posix_fallocate(3).  pmem_map_file()  will
122       fail  if PMEM_FILE_CREATE is specified without PMEM_FILE_SPARSE and the
123       underlying file system does not support posix_fallocate(3).
124

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

CAVEATS

SEE ALSO