.\" 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 2021-2022, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_vm_reservation_extend\f[R](),
\f[B]pmem2_vm_reservation_shrink\f[R]() - extends and shrinks existing
virtual memory reservation
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmem2.h>

struct pmem2_vm_reservation;
int pmem2_vm_reservation_extend(struct pmem2_vm_reservation *rsv, size_t size);
int pmem2_vm_reservation_shrink(struct pmem2_vm_reservation *rsv, size_t offset,
        size_t size);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_vm_reservation_extend\f[R]() function extends an existing
virtual memory reservation by the given \f[I]size\f[R].
For the function to succeed the size has to be aligned to an appropriate
allocation granularity.
.PP
If the \f[B]pmem2_vm_reservation_extend\f[R]() succeeds in extending a
reservation, it provides placeholder virtual memory range that starts
from an address at the end of the old reservation.
Mappings made to the reservation before extending are preserved.
.PP
The \f[B]pmem2_vm_reservation_shrink\f[R]() function shrinks the
reservation by a region specified by \f[I]offset\f[R] into the
reservation and the \f[I]size\f[R].
For the function to succeed the \f[I]size\f[R] and \f[I]offset\f[R]
variables have to be aligned to an appropriate allocation granularity.
The region formed by \f[I]offset\f[R] and \f[I]size\f[R] has to belong
to the reservation, be empty and it needs to cover the beginning or the
end of the reservation.
Shrinking reservation from the middle or shrinking the whole reservation
is not supported.
.PP
If the \f[B]pmem2_vm_reservation_shrink\f[R]() succeeds in shrinking a
reservation, it releases placeholder virtual memory range that was
designated by \f[I]offset\f[R] and \f[I]size\f[R] variables.
Mappings made to the reservation before shrinking are preserved.
.PP
If either of those functions fails, reservation will be left as it was
and appropriate error value will be returned.
.SH RETURN VALUE
.PP
The \f[B]pmem2_vm_reservation_extend\f[R]() and
\f[B]pmem2_vm_reservation_shrink\f[R]() functions return 0 on success or
a negative error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_vm_reservation_extend\f[R]() function can fail with the
following errors:
.IP \[bu] 2
\f[B]PMEM2_E_MAPPING_EXISTS\f[R] - the range that the reservation would
be extended by is already occupied by an existing mapping.
.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.
.PP
The \f[B]pmem2_vm_reservation_shrink\f[R]() function can fail with the
following errors:
.IP \[bu] 2
\f[B]PMEM2_E_OFFSET_UNALIGNED\f[R] - provided offset isn\[cq]t aligned
to an appropriate allocation granularity.
.IP \[bu] 2
\f[B]PMEM2_E_LENGTH_UNALIGNED\f[R] - provided size isn\[cq]t aligned to
an appropriate allocation granularity.
.IP \[bu] 2
\f[B]PMEM2_E_OFFSET_OUT_OF_RANGE\f[R] - provided offset is out of
reservation range available to be shrunk.
.IP \[bu] 2
\f[B]PMEM2_E_LENGTH_OUT_OF_RANGE\f[R] - provided size is out of
reservation range available to be shrunk.
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[R] - interval designated by \f[I]offset\f[R] and
\f[I]size\f[R] variables covers only the middle or the whole reservation
range.
.IP \[bu] 2
\f[B]PMEM2_VM_RESERVATION_NOT_EMPTY\f[R] - interval designated by
\f[I]offset\f[R] and \f[I]size\f[R] variable is not empty.
.PP
It can also return \f[B]-EAGAIN\f[R] and \f[B]-ENOMEM\f[R] from the
underlying \f[B]munmap\f[R](2) function.
.SH SEE ALSO
.PP
\f[B]pmem2_vm_reservation_new\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]