.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-26" "PMDK - " "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[R]() - 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[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_map_from_existing\f[R]() returns a new *struct
pmem2_map\f[B] for mapping provided by the user. This function allows
usage of \f[R]libpmem2\f[B](7) API without \f[R]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[R]pmem2_config_set_required_store_granularity\f[B](3) and
\f[R]libpmem2**(7) for more details.
.PP
For the \f[I]pmem2_map\f[R] object created by the
\f[B]pmem2_map_from_existing\f[R](3) function, the
\f[B]pmem2_map_delete\f[R](3) will only destroy the object, but it
won\[cq]t unmap the mapping this object describes.
.SH RETURN VALUE
.PP
The \f[B]pmem2_map_from_existing\f[R]() function returns 0 when it
succeeds or a negative error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_map_from_existing\f[R]() can fail with the following
errors:
.PP
\f[B]PMEM2_E_MAPPING_EXISTS\f[R] - when contiguous region
(\f[I]addr\f[R], \f[I]addr\f[R] + \f[I]len\f[R]) is already registered
by \f[I]libpmem2\f[R]
.PP
It can also return \f[B]-ENOMEM\f[R] from the underlying
\f[B]malloc\f[R](2) function.
.SH SEE ALSO
.PP
\f[B]malloc(2)\f[R], \f[B]pmem2_map_delete\f[R](3),
\f[B]pmem2_map_new\f[R](3), \f[B]pmem2_source_from_fd\f[R](3),
\f[B]libpmem2\f[R](7) and \f[B]<https://pmem.io>\f[R]