NAME

       pmem2_vm_reservation_new(),  pmem2_vm_reservation_delete()  -  creates  or deletes an instance of virtual
       memory reservation

SYNOPSIS

              #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);

DESCRIPTION

       The pmem2_vm_reservation_new() 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.

       For  the function to succeed, the addr must be either aligned to an appropriate allocation granularity or
       NULL, the size always has to be aligned to an appropriate OS allocation granularity.

       libpmem2(7) library chooses the largest page alignment for the reservation based on size.  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.

       If  the  pmem2_vm_reservation_new()  succeeds  in  creating  a  reservation, it instantiates a new struct
       pmem2_vm_reservation object describing the reservation.  The pointer to this  object  is  stored  in  the
       user-provided  variable  via the rsv_ptr pointer.  If the function fails, an appropriate error value will
       be returned.  For a list of possible return values please see RETURN VALUE

       After instantiating an object via the pmem2_vm_reservation_new() function, it may be  disposed  of  using
       the pmem2_vm_reservation_delete() function.

       The pmem2_vm_reservation_delete() function destroys the object describing the reservation and unmaps vir‐
       tual  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 rsv_ptr pointer  does  not
       contain any mappings.

RETURN VALUE

       The pmem2_vm_reservation_new() and pmem2_vm_reservation_delete() functions return 0 on success or a nega‐
       tive error code on failure.

       The function returns 0 on success or a negative error code on failure.

ERRORS

       The pmem2_vm_reservation_new() function can fail with the following errors:

       • PMEM2_E_ADDRESS_UNALIGNED - argument addr is not aligned to the appropriate allocation granularity.

       • PMEM2_E_MAPPING_EXISTS - mapping already exists in the range (addr, addr + size).

       It  can also return -EAGAIN, -ENOMEM from the underlying mmap(2) function and -ENOMEM in case of insuffi‐
       cient memory to allocate an instance of struct pmem2_vm_reservation.

       The pmem2_vm_reservation_delete() function can fail with the following errors:

       • PMEM2_E_RESERVATION_NOT_EMPTY - reservation contains mappings.

       It can also return errors from the underlying munmap(2) function.

SEE ALSO

       pmem2_config_set_vm_reservation(3), libpmem2(7) and <https://pmem.io>