pmem2_map_new - Man Page

creates a mapping


#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);


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 success or a negative error code on failure.


The pmem2_map_new() can fail with the following errors:

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 <>

Referenced By

libpmem2(7), pmem2_async(3), pmem2_config_new(3), pmem2_config_set_length(3), pmem2_config_set_offset(3), pmem2_config_set_protection(3), pmem2_config_set_sharing(3), pmem2_get_drain_fn(3), pmem2_get_flush_fn(3), pmem2_get_memmove_fn(3), pmem2_get_persist_fn(3), pmem2_map_delete(3), pmem2_map_from_existing(3), pmem2_map_get_address(3), pmem2_map_get_size(3), pmem2_map_get_store_granularity(3), pmem2_source_alignment(3), pmem2_source_from_anon(3), pmem2_source_from_fd(3).

2022-08-25 PMDK - pmem2 API version 1.0 PMDK Programmer's Manual