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              void pmem2_vm_reservation_new(struct pmem2_vm_reservation **rsv_ptr,
14                      void *addr, size_t size);
15              void 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 has to be aligned
24       to an appropraite allocation granularity.
25
26       If the pmem2_vm_reservation_new() succeeds in creating  a  reservation,
27       it instantiates a new struct pmem2_vm_reservation object describing the
28       reservation.  The pointer to this object is stored in the user-provided
29       variable  via the rsv_ptr pointer.  If the function fails, an appropri‐
30       ate error value will be returned.  For a list of possible return values
31       please see RETURN VALUE
32
33       After  instantiating an object via the pmem2_vm_reservation_new() func‐
34       tion, it may be disposed  of  using  the  pmem2_vm_reservation_delete()
35       function.
36
37       The pmem2_vm_reservation_delete() function destroys the object describ‐
38       ing the reservation  and  unmaps  virtual  memory  region  the  *struct
39       pmem2_vm_reservation** had assigned during the initialization.  For the
40       delete function to succeed, it is required that the reservation  passed
41       via the rsv_ptr pointer does not contain any mappings.
42

RETURN VALUE

44       The  pmem2_vm_reservation_new() and pmem2_vm_reservation_delete() func‐
45       tions return 0 on success or a negative error code on failure.
46
47       The function returns 0 on success or a negative error code on failure.
48

ERRORS

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

ERRORS

71       The pmem2_vm_reservation_new() and pmem2_vm_reservation_delete()  func‐
72       tions are not supported yet.
73

SEE ALSO

75       pmem2_config_set_vm_reservation(3), libpmem2(7) and <http://pmem.io>
76
77
78
79PMDK - pmem2 API version 1.0      2020-10-28       PMEM2_VM_RESERVATION_NEW(3)