pmem2 API version 1.0

The PMDK repository on GitHub is the ultimate source of information on PMDK from release 2.0! For all questions and to submit eventual issues please follow to that repository. The PMDK documentation collected here should be valid up to the 1.13.1 release but is maintained only on a best-effort basis and may not reflect the latest state of the art.

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO

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

The contents of this web site and the associated GitHub repositories are BSD-licensed open source.