NAME

       pmem2_map_new() - creates a mapping

SYNOPSIS

              #include <libpmem2.h>

              struct pmem2_config;
              struct pmem2_source;
              struct pmem2_map;
              int pmem2_map_new(struct pmem2_map **map_ptr, const struct pmem2_config *config,
                      const struct pmem2_source *source);

DESCRIPTION

       The  pmem2_map_new()  function creates a new mapping in the virtual address space of the calling process.
       This function requires a configuration config of the mapping and the data source source.

       Optionally, the mapping can be created at the offset of the virtual memory reservation set in the config‐
       uration config.  See pmem2_config_set_vm_reservation(3) for details.

       For a mapping to succeed, the config structure must have the granularity parameter set to the appropriate
       level.  See pmem2_config_set_required_store_granularity(3) and libpmem2(7) for more details.

       If the pmem2_map_new() function succeeds in  creating  a  new  mapping  it  instantiates  a  new  *struct
       pmem2_map**  object  describing  the  mapping.  The pointer to this newly created object is stored in the
       user-provided variable passed via the map_ptr pointer.  If the mapping  fails  the  variable  pointed  by
       map_ptr  will  contain a NULL value and appropriate error value will be returned.  For a list of possible
       return values please see RETURN VALUE.

       All struct pmem2_map objects created via the pmem2_map_new() function have  to  be  destroyed  using  the
       pmem2_map_delete() function.  For details please see pmem2_map_delete(3) manual page.

RETURN VALUE

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

ERRORS

       The pmem2_map_new() can fail with the following errors:

       • PMEM2_E_GRANULARITY_NOT_SET  - the store granularity for the mapping was not set in the provided config
         structure.  Please see pmem2_config_set_required_store_granularity(3) and libpmem2(7).

       • PMEM2_E_MAP_RANGE - offset + length is too big to represent it using size_t data type

       • PMEM2_E_MAP_RANGE - end of the mapping (offset + length) is outside of  the  file.   The  file  is  too
         small.

       • PMEM2_E_SOURCE_EMPTY - mapped file has size equal to 0.

       • PMEM2_E_MAPPING_EXISTS - if the object exists before the function call.  For details please see Create‐
         FileMapping() manual pages.  (Windows only)

       • PMEM2_E_OFFSET_UNALIGNED  -  argument unaligned, offset is not a multiple of the alignment required for
         specific *source.  Please see pmem2_source_alignment(3).

       • PMEM2_E_LENGTH_UNALIGNED - argument unaligned, length is not a multiple of the alignment  required  for
         specific *source.  Please see pmem2_source_alignment(3).

       • PMEM2_E_SRC_DEVDAX_PRIVATE - device DAX mapped with MAP_PRIVATE.  (Linux only)

       • PMEM2_E_ADDRESS_UNALIGNED  -  when mapping device DAX to a virtual memory reservation and the base map‐
         ping address (reservation address + reservation offset) is not aligned to the device  DAX  granularity.
         Please see pmem2_config_set_vm_reservation(3).  (Linux only)

       • PMEM2_E_ADDRESS_UNALIGNED - when mapping to a virtual memory reservation and the region for the mapping
         exceeds reservation size.  Please see pmem2_config_set_vm_reservation(3).

       • PMEM2_E_NOSUPP - when config-provided protection flags combination is not supported.

       • PMEM2_E_NO_ACCESS - there is a conflict between mapping protection and file opening mode.

       It  can also return -EACCES, -EAGAIN, -EBADF, -ENFILE, -ENODEV, -ENOMEM, -EPERM, -ETXTBSY from the under‐
       lying mmap(2) function.  It is used with and without MAP_ANONYMOUS.

       -EACCES may be returned only if the file descriptor points to an append-only file.

       It can also return all errors from the underlying pmem2_source_size() and pmem2_source_alignment()  func‐
       tions.

SEE ALSO

       mmap(2),      open(3),     pmem2_config_set_required_store_granularity(3),     pmem2_source_alignment(3),
       pmem2_source_from_fd(3), pmem2_source_size(3),  pmem2_map_delete(3),  pmem2_config_set_vm_reservation(3),
       libpmem2(7) and <https://pmem.io>