.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_MAP_NEW" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "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[]() \- 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[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_map_new\f[]() function creates a new mapping in the
virtual address space of the calling process.
This function requires a configuration \f[I]config\f[] of the mapping
and the data source \f[I]source\f[].
.PP
Optionally, the mapping can be created at the offset of the virtual
memory reservation set in the configuration \f[I]config\f[].
See \f[B]pmem2_config_set_vm_reservation\f[](3) for details.
.PP
For a mapping to succeed, the \f[I]config\f[] structure must have the
granularity parameter set to the appropriate level.
See \f[B]pmem2_config_set_required_store_granularity\f[](3) and
\f[B]libpmem2\f[](7) for more details.
.PP
If the \f[B]pmem2_map_new\f[]() 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[] pointer.
If the mapping fails the variable pointed by \f[I]map_ptr\f[] 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[] objects created via the
\f[B]pmem2_map_new\f[]() function have to be destroyed using the
\f[B]pmem2_map_delete\f[]() function.
For details please see \f[B]pmem2_map_delete\f[](3) manual page.
.SH RETURN VALUE
.PP
The \f[B]pmem2_map_new\f[]() function returns 0 on success or a negative
error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_map_new\f[]() can fail with the following errors:
.IP \[bu] 2
\f[B]PMEM2_E_GRANULARITY_NOT_SET\f[] \- the store granularity for the
mapping was not set in the provided \f[I]config\f[] structure.
Please see \f[B]pmem2_config_set_required_store_granularity\f[](3) and
\f[B]libpmem2\f[](7).
.IP \[bu] 2
\f[B]PMEM2_E_MAP_RANGE\f[] \- \f[I]offset\f[] + \f[I]length\f[] is too
big to represent it using \f[I]size_t\f[] data type
.IP \[bu] 2
\f[B]PMEM2_E_MAP_RANGE\f[] \- end of the mapping (\f[I]offset\f[] +
\f[I]length\f[]) is outside of the file.
The file is too small.
.IP \[bu] 2
\f[B]PMEM2_E_SOURCE_EMPTY\f[] \- mapped file has size equal to 0.
.IP \[bu] 2
\f[B]PMEM2_E_MAPPING_EXISTS\f[] \- if the object exists before the
function call.
For details please see \f[B]CreateFileMapping\f[]() manual pages.
(Windows only)
.IP \[bu] 2
\f[B]PMEM2_E_OFFSET_UNALIGNED\f[] \- argument unaligned, offset is not a
multiple of the alignment required for specific \f[I]*source\f[].
Please see \f[B]pmem2_source_alignment\f[](3).
.IP \[bu] 2
\f[B]PMEM2_E_LENGTH_UNALIGNED\f[] \- argument unaligned, length is not a
multiple of the alignment required for specific \f[I]*source\f[].
Please see \f[B]pmem2_source_alignment\f[](3).
.IP \[bu] 2
\f[B]PMEM2_E_SRC_DEVDAX_PRIVATE\f[] \- device DAX mapped with
MAP_PRIVATE.
(Linux only)
.IP \[bu] 2
\f[B]PMEM2_E_ADDRESS_UNALIGNED\f[] \- 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[](3).
(Linux only)
.IP \[bu] 2
\f[B]PMEM2_E_ADDRESS_UNALIGNED\f[] \- 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[](3).
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[] \- when config\-provided protection flags
combination is not supported.
.IP \[bu] 2
\f[B]PMEM2_E_NO_ACCESS\f[] \- there is a conflict between mapping
protection and file opening mode.
.PP
It can also return \f[B]\-EACCES\f[], \f[B]\-EAGAIN\f[],
\f[B]\-EBADF\f[], \f[B]\-ENFILE\f[], \f[B]\-ENODEV\f[],
\f[B]\-ENOMEM\f[], \f[B]\-EPERM\f[], \f[B]\-ETXTBSY\f[] from the
underlying \f[B]mmap\f[](2) function.
It is used with and without \f[B]MAP_ANONYMOUS\f[].
.PP
\f[B]\-EACCES\f[] 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[]() and \f[B]pmem2_source_alignment\f[]()
functions.
.SH SEE ALSO
.PP
\f[B]mmap\f[](2), \f[B]open\f[](3),
\f[B]pmem2_config_set_required_store_granularity\f[](3),
\f[B]pmem2_source_alignment\f[](3), \f[B]pmem2_source_from_fd\f[](3),
\f[B]pmem2_source_size\f[](3), \f[B]pmem2_map_delete\f[](3),
\f[B]pmem2_config_set_vm_reservation\f[](3), \f[B]libpmem2\f[](7) and
\f[B]<https://pmem.io>\f[]