.\" 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_vm_reservation_new\f[R](),
\f[B]pmem2_vm_reservation_delete\f[R]() - creates or deletes an instance
of virtual memory reservation
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmem2.h>

struct pmem2_vm_reservation;
int pmem2_vm_reservation_new(struct pmem2_vm_reservation **rsv_ptr,
        void *addr, size_t size);
int pmem2_vm_reservation_delete(struct pmem2_vm_reservation **rsv_ptr);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_vm_reservation_new\f[R]() function creates a new blank
mapping in the virtual address space of the calling process.
Reservation serves as a placeholder of a given size on which sources can
be mapped.
.PP
For the function to succeed, the \f[I]addr\f[R] must be either aligned
to an appropriate allocation granularity or \f[B]NULL\f[R], the size
always has to be aligned to an appropriate OS allocation granularity.
.PP
\f[B]libpmem2\f[R](7) library chooses the largest page alignment for the
reservation based on \f[I]size\f[R].
If the chosen alignment is different than the OS allocation granularity,
then the underlying size of the reservation can be bigger than the value
presented to the user.
Largest page alignment functionality is limited to POSIX systems.
.PP
If the \f[B]pmem2_vm_reservation_new\f[R]() succeeds in creating a
reservation, it instantiates a new \f[B]struct pmem2_vm_reservation\f[R]
object describing the reservation.
The pointer to this object is stored in the user-provided variable via
the \f[I]rsv_ptr\f[R] pointer.
If the function fails, an appropriate error value will be returned.
For a list of possible return values please see RETURN VALUE
.PP
After instantiating an object via the
\f[B]pmem2_vm_reservation_new\f[R]() function, it may be disposed of
using the \f[B]pmem2_vm_reservation_delete\f[R]() function.
.PP
The \f[B]pmem2_vm_reservation_delete\f[R]() function destroys the object
describing the reservation and unmaps virtual memory region the *struct
pmem2_vm_reservation** had assigned during the initialization.
For the delete function to succeed, it is required that the reservation
passed via the \f[I]rsv_ptr\f[R] pointer does not contain any mappings.
.SH RETURN VALUE
.PP
The \f[B]pmem2_vm_reservation_new\f[R]() and
\f[B]pmem2_vm_reservation_delete\f[R]() functions return 0 on success or
a negative error code on failure.
.PP
The function returns 0 on success or a negative error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_vm_reservation_new\f[R]() function can fail with the
following errors:
.IP \[bu] 2
\f[B]PMEM2_E_ADDRESS_UNALIGNED\f[R] - argument \f[I]addr\f[R] is not
aligned to the appropriate allocation granularity.
.IP \[bu] 2
\f[B]PMEM2_E_MAPPING_EXISTS\f[R] - mapping already exists in the range
(\f[I]addr\f[R], \f[I]addr\f[R] + \f[I]size\f[R]).
.PP
It can also return \f[B]-EAGAIN\f[R], \f[B]-ENOMEM\f[R] from the
underlying \f[B]mmap\f[R](2) function and \f[B]-ENOMEM\f[R] in case of
insufficient memory to allocate an instance of \f[I]struct
pmem2_vm_reservation\f[R].
.PP
The \f[B]pmem2_vm_reservation_delete\f[R]() function can fail with the
following errors:
.IP \[bu] 2
\f[B]PMEM2_E_RESERVATION_NOT_EMPTY\f[R] - reservation contains mappings.
.PP
It can also return errors from the underlying \f[B]munmap\f[R](2)
function.
.SH SEE ALSO
.PP
\f[B]pmem2_config_set_vm_reservation\f[R](3), \f[B]libpmem2\f[R](7) and
\f[B]<https://pmem.io>\f[R]