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

RETURN VALUE

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

NOTES

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

CAVEATS

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

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

CAVEATS

SEE ALSO