.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_MAP_FROM_EXISTING" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2020-2021, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_map_from_existing\f[]() \- creates a pmem2_map object from an
existing mapping
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <libpmem2.h>

int\ pmem2_map_from_existing(struct\ pmem2_map\ **map,\ const\ struct\ pmem2_source\ *src,
\ \ \ \ void\ *addr,\ size_t\ len,\ enum\ pmem2_granularity\ gran);
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_map_from_existing\f[]() returns a new *struct
pmem2_map\f[B] for mapping provided by the user. This function allows
usage of \f[]libpmem2\f[B](7) API without \f[]pmem2_map_new\f[B](3) for
mapping file. Mapping is defined by \f[BI]addr\f[B] and \f[BI]len\f[B].
You have to specify underlying file as a \f[BI]src\f[B], and define
granularity of this mapping. See
\f[]pmem2_config_set_required_store_granularity\f[B](3) and
\f[]libpmem2**(7) for more details.
.PP
For the \f[I]pmem2_map\f[] object created by the
\f[B]pmem2_map_from_existing\f[](3) function, the
\f[B]pmem2_map_delete\f[](3) will only destroy the object, but it won't
unmap the mapping this object describes.
.SH RETURN VALUE
.PP
The \f[B]pmem2_map_from_existing\f[]() function returns 0 when it
succeeds or a negative error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_map_from_existing\f[]() can fail with the following
errors:
.PP
\f[B]PMEM2_E_MAPPING_EXISTS\f[] \- when contiguous region
(\f[I]addr\f[], \f[I]addr\f[] + \f[I]len\f[]) is already registered by
\f[I]libpmem2\f[]
.PP
It can also return \f[B]\-ENOMEM\f[] from the underlying
\f[B]malloc\f[](2) function.
.SH SEE ALSO
.PP
\f[B]malloc(2)\f[], \f[B]pmem2_map_delete\f[](3),
\f[B]pmem2_map_new\f[](3), \f[B]pmem2_source_from_fd\f[](3),
\f[B]libpmem2\f[](7) and \f[B]<https://pmem.io>\f[]