PMEM2_MAP(3)

NAME

pmem2_map() - creates a mapping

SYNOPSIS

    #include <libpmem2.h>
    struct pmem2_config;
    struct pmem2_source;
    struct pmem2_map;
    int pmem2_map(const struct pmem2_config *config, const struct pmem2_source *source,
        struct pmem2_map **map_ptr);

DESCRIPTION

The pmem2_map() 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.

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() 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() function have to be destroyed using the pmem2_unmap() function. For details please see pmem2_unmap(3) manual page.

RETURN VALUE

When pmem2_map() succeeds it returns 0. Otherwise, it returns one of the following error values:

•   PMEM2_E_GRANULARITY_NOT_SET - the store granularity for the mapping was not set in the provided config structure. Please seepmem2_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_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_unmap(3), libpmem2(7) and <http://pmem.io>