pmem2_map_new(3)

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

NAME

6       pmem2_map_new() - creates a mapping
7

SYNOPSIS

9              #include <libpmem2.h>
10
11              struct pmem2_config;
12              struct pmem2_source;
13              struct pmem2_map;
14              int pmem2_map_new(struct pmem2_map **map_ptr, const struct pmem2_config *config,
15                      const struct pmem2_source *source);
16

DESCRIPTION

18       The  pmem2_map_new()  function creates a new mapping in the virtual ad‐
19       dress space of the calling process.  This function requires a  configu‐
20       ration config of the mapping and the data source source.
21
22       Optionally,  the  mapping  can  be created at the offset of the virtual
23       memory reservation set in the  configuration  config.   See  pmem2_con‐
24       fig_set_vm_reservation(3) for details.
25
26       For a mapping to succeed, the config structure must have the granulari‐
27       ty parameter set to the appropriate  level.   See  pmem2_config_set_re‐
28       quired_store_granularity(3) and libpmem2(7) for more details.
29
30       If  the  pmem2_map_new() function succeeds in creating a new mapping it
31       instantiates a new *struct pmem2_map** object describing  the  mapping.
32       The pointer to this newly created object is stored in the user-provided
33       variable passed via the map_ptr pointer.   If  the  mapping  fails  the
34       variable  pointed  by map_ptr will contain a NULL value and appropriate
35       error value will be returned.  For a list  of  possible  return  values
36       please see RETURN VALUE.
37
38       All  struct  pmem2_map objects created via the pmem2_map_new() function
39       have to be destroyed using the pmem2_map_delete()  function.   For  de‐
40       tails please see pmem2_map_delete(3) manual page.
41

RETURN VALUE

43       The  pmem2_map_new()  function returns 0 on success or a negative error
44       code on failure.
45

ERRORS

47       The pmem2_map_new() can fail with the following errors:
48
49       • PMEM2_E_GRANULARITY_NOT_SET - the store granularity for  the  mapping
50         was  not set in the provided config structure.  Please see pmem2_con‐
51         fig_set_required_store_granularity(3) and libpmem2(7).
52
53       • PMEM2_E_MAP_RANGE - offset + length is too big to represent it  using
54         size_t data type
55
56       • PMEM2_E_MAP_RANGE  -  end of the mapping (offset + length) is outside
57         of the file.  The file is too small.
58
59       • PMEM2_E_SOURCE_EMPTY - mapped file has size equal to 0.
60
61       • PMEM2_E_MAPPING_EXISTS - if the object  exists  before  the  function
62         call.   For  details  please  see  CreateFileMapping()  manual pages.
63         (Windows only)
64
65       • PMEM2_E_OFFSET_UNALIGNED - argument unaligned, offset is not a multi‐
66         ple  of  the  alignment  required  for  specific *source.  Please see
67         pmem2_source_alignment(3).
68
69       • PMEM2_E_LENGTH_UNALIGNED - argument unaligned, length is not a multi‐
70         ple  of  the  alignment  required  for  specific *source.  Please see
71         pmem2_source_alignment(3).
72
73       • PMEM2_E_SRC_DEVDAX_PRIVATE -  device  DAX  mapped  with  MAP_PRIVATE.
74         (Linux only)
75
76       • PMEM2_E_ADDRESS_UNALIGNED - when mapping device DAX to a virtual mem‐
77         ory reservation and the base mapping address (reservation  address  +
78         reservation  offset)  is  not  aligned to the device DAX granularity.
79         Please see pmem2_config_set_vm_reservation(3).  (Linux only)
80
81       • PMEM2_E_ADDRESS_UNALIGNED - when mapping to a virtual memory reserva‐
82         tion and the region for the mapping exceeds reservation size.  Please
83         see pmem2_config_set_vm_reservation(3).
84
85       • PMEM2_E_NOSUPP - when config-provided protection flags combination is
86         not supported.
87
88       • PMEM2_E_NO_ACCESS  -  there  is a conflict between mapping protection
89         and file opening mode.
90
91       It can also return -EACCES, -EAGAIN, -EBADF, -ENFILE, -ENODEV, -ENOMEM,
92       -EPERM, -ETXTBSY from the underlying mmap(2) function.  It is used with
93       and without MAP_ANONYMOUS.
94
95       -EACCES may be returned only if the file descriptor points  to  an  ap‐
96       pend-only file.
97
98       It  can  also return all errors from the underlying pmem2_source_size()
99       and pmem2_source_alignment() functions.
100

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

SEE ALSO