1PMEM2_VM_RESERVATION_EXTEND(P3M)DK Programmer's ManuPaMlEM2_VM_RESERVATION_EXTEND(3)
2
3
4

NAME

6       pmem2_vm_reservation_extend(),  pmem2_vm_reservation_shrink() - extends
7       and shrinks existing virtual memory reservation
8

SYNOPSIS

10              #include <libpmem2.h>
11
12              struct pmem2_vm_reservation;
13              int pmem2_vm_reservation_extend(struct pmem2_vm_reservation *rsv, size_t size);
14              int pmem2_vm_reservation_shrink(struct pmem2_vm_reservation *rsv, size_t offset,
15                      size_t size);
16

DESCRIPTION

18       The pmem2_vm_reservation_extend() function extends an existing  virtual
19       memory  reservation by the given size.  For the function to succeed the
20       size has to be aligned to an appropriate allocation granularity.
21
22       If the pmem2_vm_reservation_extend() succeeds in extending  a  reserva‐
23       tion,  it provides placeholder virtual memory range that starts from an
24       address at the end of the old reservation.  Mappings made to the reser‐
25       vation before extending are preserved.
26
27       The pmem2_vm_reservation_shrink() function shrinks the reservation by a
28       region specified by offset into the reservation and the size.  For  the
29       function to succeed the size and offset variables have to be aligned to
30       an appropriate allocation granularity.  The region formed by offset and
31       size  has  to belong to the reservation, be empty and it needs to cover
32       the beginning or the end of  the  reservation.   Shrinking  reservation
33       from the middle or shrinking the whole reservation is not supported.
34
35       If  the  pmem2_vm_reservation_shrink() succeeds in shrinking a reserva‐
36       tion, it releases placeholder virtual memory range that was  designated
37       by  offset and size variables.  Mappings made to the reservation before
38       shrinking are preserved.
39
40       If either of those functions fails, reservation will be left as it  was
41       and appropriate error value will be returned.
42

RETURN VALUE

44       The   pmem2_vm_reservation_extend()  and  pmem2_vm_reservation_shrink()
45       functions return 0 on success or a negative error code on failure.
46

ERRORS

48       The pmem2_vm_reservation_extend() function can fail with the  following
49       errors:
50
51       • PMEM2_E_MAPPING_EXISTS  - the range that the reservation would be ex‐
52         tended by is already occupied by an existing mapping.
53
54       It can also return -EAGAIN, -ENOMEM from the underlying  mmap(2)  func‐
55       tion.
56
57       The  pmem2_vm_reservation_shrink() function can fail with the following
58       errors:
59
60       • PMEM2_E_OFFSET_UNALIGNED - provided offset isn't aligned to an appro‐
61         priate allocation granularity.
62
63       • PMEM2_E_LENGTH_UNALIGNED  -  provided size isn't aligned to an appro‐
64         priate allocation granularity.
65
66       • PMEM2_E_OFFSET_OUT_OF_RANGE - provided offset is out  of  reservation
67         range available to be shrunk.
68
69       • PMEM2_E_LENGTH_OUT_OF_RANGE  -  provided  size  is out of reservation
70         range available to be shrunk.
71
72       • PMEM2_E_NOSUPP - interval designated by  offset  and  size  variables
73         covers only the middle or the whole reservation range.
74
75       • PMEM2_VM_RESERVATION_NOT_EMPTY  -  interval  designated by offset and
76         size variable is not empty.
77
78       It can also return -EAGAIN and -ENOMEM from  the  underlying  munmap(2)
79       function.
80

SEE ALSO

82       pmem2_vm_reservation_new(3),  pmem2_config_set_vm_reservation(3), libp‐
83       mem2(7) and <https://pmem.io>
84
85
86
87PMDK - pmem2 API version 1.0      2022-05-24    PMEM2_VM_RESERVATION_EXTEND(3)
Impressum