Man page - pmem2_map_new(3)

Packages contains this manual

Package: libpmem2-dev
apt-get install libpmem2-dev

Manuals in package:

Documentations in package:

libpmem2-dev

Manual

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
SEE ALSO

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