.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-31" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2019-2021, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_map_new\f[R]() - creates a mapping
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_map_new\f[R]() function creates a new mapping in the
virtual address space of the calling process.
This function requires a configuration \f[I]config\f[R] of the mapping
and the data source \f[I]source\f[R].
.PP
Optionally, the mapping can be created at the offset of the virtual
memory reservation set in the configuration \f[I]config\f[R].
See \f[B]pmem2_config_set_vm_reservation\f[R](3) for details.
.PP
For a mapping to succeed, the \f[I]config\f[R] structure must have the
granularity parameter set to the appropriate level.
See \f[B]pmem2_config_set_required_store_granularity\f[R](3) and
\f[B]libpmem2\f[R](7) for more details.
.PP
If the \f[B]pmem2_map_new\f[R]() 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 \f[I]map_ptr\f[R] pointer.
If the mapping fails the variable pointed by \f[I]map_ptr\f[R] will
contain a NULL value and appropriate error value will be returned.
For a list of possible return values please see RETURN VALUE.
.PP
All \f[I]struct pmem2_map\f[R] objects created via the
\f[B]pmem2_map_new\f[R]() function have to be destroyed using the
\f[B]pmem2_map_delete\f[R]() function.
For details please see \f[B]pmem2_map_delete\f[R](3) manual page.
.SH RETURN VALUE
.PP
The \f[B]pmem2_map_new\f[R]() function returns 0 on success or a
negative error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_map_new\f[R]() can fail with the following errors:
.IP \[bu] 2
\f[B]PMEM2_E_GRANULARITY_NOT_SET\f[R] - the store granularity for the
mapping was not set in the provided \f[I]config\f[R] structure.
Please see \f[B]pmem2_config_set_required_store_granularity\f[R](3) and
\f[B]libpmem2\f[R](7).
.IP \[bu] 2
\f[B]PMEM2_E_MAP_RANGE\f[R] - \f[I]offset\f[R] + \f[I]length\f[R] is too
big to represent it using \f[I]size_t\f[R] data type
.IP \[bu] 2
\f[B]PMEM2_E_MAP_RANGE\f[R] - end of the mapping (\f[I]offset\f[R] +
\f[I]length\f[R]) is outside of the file.
The file is too small.
.IP \[bu] 2
\f[B]PMEM2_E_SOURCE_EMPTY\f[R] - mapped file has size equal to 0.
.IP \[bu] 2
\f[B]PMEM2_E_MAPPING_EXISTS\f[R] - if the object exists before the
function call.
For details please see \f[B]CreateFileMapping\f[R]() manual pages.
(Windows only)
.IP \[bu] 2
\f[B]PMEM2_E_OFFSET_UNALIGNED\f[R] - argument unaligned, offset is not a
multiple of the alignment required for specific \f[I]*source\f[R].
Please see \f[B]pmem2_source_alignment\f[R](3).
.IP \[bu] 2
\f[B]PMEM2_E_LENGTH_UNALIGNED\f[R] - argument unaligned, length is not a
multiple of the alignment required for specific \f[I]*source\f[R].
Please see \f[B]pmem2_source_alignment\f[R](3).
.IP \[bu] 2
\f[B]PMEM2_E_SRC_DEVDAX_PRIVATE\f[R] - device DAX mapped with
MAP_PRIVATE.
(Linux only)
.IP \[bu] 2
\f[B]PMEM2_E_ADDRESS_UNALIGNED\f[R] - 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 \f[B]pmem2_config_set_vm_reservation\f[R](3).
(Linux only)
.IP \[bu] 2
\f[B]PMEM2_E_ADDRESS_UNALIGNED\f[R] - when mapping to a virtual memory
reservation and the region for the mapping exceeds reservation size.
Please see \f[B]pmem2_config_set_vm_reservation\f[R](3).
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[R] - when config-provided protection flags
combination is not supported.
.IP \[bu] 2
\f[B]PMEM2_E_NO_ACCESS\f[R] - there is a conflict between mapping
protection and file opening mode.
.PP
It can also return \f[B]-EACCES\f[R], \f[B]-EAGAIN\f[R],
\f[B]-EBADF\f[R], \f[B]-ENFILE\f[R], \f[B]-ENODEV\f[R],
\f[B]-ENOMEM\f[R], \f[B]-EPERM\f[R], \f[B]-ETXTBSY\f[R] from the
underlying \f[B]mmap\f[R](2) function.
It is used with and without \f[B]MAP_ANONYMOUS\f[R].
.PP
\f[B]-EACCES\f[R] may be returned only if the file descriptor points to
an append-only file.
.PP
It can also return all errors from the underlying
\f[B]pmem2_source_size\f[R]() and \f[B]pmem2_source_alignment\f[R]()
functions.
.SH SEE ALSO
.PP
\f[B]mmap\f[R](2), \f[B]open\f[R](3),
\f[B]pmem2_config_set_required_store_granularity\f[R](3),
\f[B]pmem2_source_alignment\f[R](3), \f[B]pmem2_source_from_fd\f[R](3),
\f[B]pmem2_source_size\f[R](3), \f[B]pmem2_map_delete\f[R](3),
\f[B]pmem2_config_set_vm_reservation\f[R](3), \f[B]libpmem2\f[R](7) and
\f[B]<https://pmem.io>\f[R]