pmem2_vm_reservation_delete(3)

1PMEM2_VM_RESERVATION_NEW(3)PMDK Programmer's ManualPMEM2_VM_RESERVATION_NEW(3)
2
3
4

NAME

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

SYNOPSIS

10              #include <libpmem2.h>
11
12              struct pmem2_vm_reservation;
13              int pmem2_vm_reservation_new(struct pmem2_vm_reservation **rsv_ptr,
14                      void *addr, size_t size);
15              int pmem2_vm_reservation_delete(struct pmem2_vm_reservation **rsv_ptr);
16

DESCRIPTION

18       The pmem2_vm_reservation_new() function creates a new blank mapping  in
19       the  virtual  address space of the calling process.  Reservation serves
20       as a placeholder of a given size on which sources can be mapped.
21
22       For the function to succeed, the addr must be either aligned to an  ap‐
23       propriate  allocation  granularity  or  NULL, the size always has to be
24       aligned to an appropriate OS allocation granularity.
25
26       libpmem2(7) library chooses the largest page alignment for the reserva‐
27       tion  based  on size.  If the chosen alignment is different than the OS
28       allocation granularity, then the underlying size of the reservation can
29       be bigger than the value presented to the user.  Largest page alignment
30       functionality is limited to POSIX systems.
31
32       If the pmem2_vm_reservation_new() succeeds in creating  a  reservation,
33       it instantiates a new struct pmem2_vm_reservation object describing the
34       reservation.  The pointer to this object is stored in the user-provided
35       variable  via the rsv_ptr pointer.  If the function fails, an appropri‐
36       ate error value will be returned.  For a list of possible return values
37       please see RETURN VALUE
38
39       After  instantiating an object via the pmem2_vm_reservation_new() func‐
40       tion, it may be disposed  of  using  the  pmem2_vm_reservation_delete()
41       function.
42
43       The pmem2_vm_reservation_delete() function destroys the object describ‐
44       ing the reservation  and  unmaps  virtual  memory  region  the  *struct
45       pmem2_vm_reservation** had assigned during the initialization.  For the
46       delete function to succeed, it is required that the reservation  passed
47       via the rsv_ptr pointer does not contain any mappings.
48

RETURN VALUE

50       The  pmem2_vm_reservation_new() and pmem2_vm_reservation_delete() func‐
51       tions return 0 on success or a negative error code on failure.
52
53       The function returns 0 on success or a negative error code on failure.
54

ERRORS

56       The pmem2_vm_reservation_new() function can fail with the following er‐
57       rors:
58
59       • PMEM2_E_ADDRESS_UNALIGNED  -  argument addr is not aligned to the ap‐
60         propriate allocation granularity.
61
62       • PMEM2_E_MAPPING_EXISTS - mapping already exists in the  range  (addr,
63         addr + size).
64
65       It  can  also return -EAGAIN, -ENOMEM from the underlying mmap(2) func‐
66       tion and -ENOMEM in case of insufficient memory to allocate an instance
67       of struct pmem2_vm_reservation.
68
69       The  pmem2_vm_reservation_delete() function can fail with the following
70       errors:
71
72       • PMEM2_E_RESERVATION_NOT_EMPTY - reservation contains mappings.
73
74       It can also return errors from the underlying munmap(2) function.
75

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

SEE ALSO