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 configuration 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 succeeds 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 CreateFileMapping() 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_alignement(3).

       • PMEM2_E_LENGTH_UNALIGNED - argument unaligned, length is not a multiple of the alignment
         required for specific *source.  Please see pmem2_source_alignement(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 mapping 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 underlying 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() functions.

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>