1PMEMCTO_MALLOC(3)          PMDK Programmer's Manual          PMEMCTO_MALLOC(3)
2
3
4

NAME

6       pmemcto_malloc,  pmemcto_free,  pmemcto_calloc, pmemcto_realloc - allo‐
7       cate and free persistent memory
8

SYNOPSIS

10              #include <libpmemcto.h>
11
12              void *pmemcto_malloc(PMEMctopool *pcp, size_t size);
13              void pmemcto_free(PMEMctopool *pcp, void *ptr);
14              void *pmemcto_calloc(PMEMctopool *pcp, size_t nmemb, size_t size);
15              void *pmemcto_realloc(PMEMctopool *pcp, void *ptr, size_t size);
16

DESCRIPTION

18       The pmemcto_malloc() function provides the same semantics as malloc(3),
19       but  operates  on  the memory pool pcp instead of the process heap sup‐
20       plied by the system.  It allocates size bytes and returns a pointer  to
21       the  allocated  memory.   The memory is not initialized.  If size is 0,
22       then pmemcto_malloc() returns either NULL, or a  unique  pointer  value
23       that can later be successfully passed to pmemcto_free().
24
25       The pmemcto_free() function provides the same semantics as free(3), but
26       operates on the memory pool pcp instead of the process heap supplied by
27       the  system.   It  frees the memory space pointed to by ptr, which must
28       have been returned by a previous call to pmemcto_malloc(), pmemcto_cal‐
29       loc()  or pmemcto_realloc() for the same pool of memory.  Undefined be‐
30       havior occurs if frees do not correspond to allocated memory  from  the
31       same memory pool.  If ptr is NULL, no operation is performed.
32
33       The pmemcto_calloc() function provides the same semantics as calloc(3),
34       but operates on the memory pool pcp instead of the  process  heap  sup‐
35       plied  by  the  system.  It allocates memory for an array of nmemb ele‐
36       ments of size bytes each and returns a pointer to the allocated memory.
37       The  memory  is  set to zero.  If nmemb or size is 0, then pmemcto_cal‐
38       loc() returns either NULL, or a unique pointer value that can later  be
39       successfully passed to pmemcto_free().
40
41       The  pmemcto_realloc()  function  provides  the same semantics as real‐
42       loc(3), but operates on the memory pool pcp instead of the process heap
43       supplied by the system.  It changes the size of the memory block point‐
44       ed to by ptr to size bytes.  The contents  will  be  unchanged  in  the
45       range from the start of the region up to the minimum of the old and new
46       sizes.  If the new size is larger than the old size, the  added  memory
47       will  not  be initialized.  If ptr is NULL, then the call is equivalent
48       to pmemcto_malloc(pcp, size), for all values of size; if size is  equal
49       to  zero  and  ptr  is  not NULL, then the call is equivalent to pmemc‐
50       to_free(pcp, ptr).  Unless ptr is NULL, it must have been  returned  by
51       an  earlier  call  to pmemcto_malloc(), pmemcto_calloc(), pmemcto_real‐
52       loc() or pmemcto_aligned_alloc(3).  If the area pointed to was moved, a
53       pmemcto_free(pcp, ptr) is done.
54

RETURN VALUE

56       On  success,  pmemcto_malloc()  and pmemcto_calloc() functions return a
57       pointer to the allocated memory.  If the allocation request  cannot  be
58       satisfied, a NULL pointer is returned and errno is set appropriately.
59
60       The pmemcto_free() function returns no value.
61
62       On  success,  pmemcto_realloc() function returns a pointer to the newly
63       allocated memory, or NULL if it is unable to satisfy the allocation re‐
64       quest.  If size was equal to 0, either NULL or a pointer suitable to be
65       passed to pmemcto_free() is returned.  If pmemcto_realloc()  fails  the
66       original block is left untouched; it is not freed or moved.
67

ERRORS

69       ENOMEM Insufficient memory available to satisfy allocation request.
70

NOTES

72       Unlike the normal malloc(), which asks the system for additional memory
73       when it runs out, libpmemcto(7) allocates the size it is  told  to  and
74       never attempts to grow or shrink that memory pool.
75

SEE ALSO

77       jemalloc(3),  malloc(3),  pmemcto_aligned_alloc(3),  libpmemcto(7)  and
78       <http://pmem.io>
79
80
81
82PMDK - libpmemcto API version 1.0 2018-07-20                 PMEMCTO_MALLOC(3)
Impressum