NAME

       pmemcto_malloc, pmemcto_free, pmemcto_calloc, pmemcto_realloc - allocate and free persistent memory

SYNOPSIS

              #include <libpmemcto.h>

              void *pmemcto_malloc(PMEMctopool *pcp, size_t size);
              void pmemcto_free(PMEMctopool *pcp, void *ptr);
              void *pmemcto_calloc(PMEMctopool *pcp, size_t nmemb, size_t size);
              void *pmemcto_realloc(PMEMctopool *pcp, void *ptr, size_t size);

DESCRIPTION

       The  pmemcto_malloc()  function provides the same semantics as malloc(3), but operates on the memory pool
       pcp instead of the process heap supplied by the system.  It allocates size bytes and returns a pointer to
       the allocated memory.  The memory is not initialized.  If size is 0, then pmemcto_malloc() returns either
       NULL, or a unique pointer value that can later be successfully passed to pmemcto_free().

       The pmemcto_free() function provides the same semantics as free(3), but operates on the memory  pool  pcp
       instead  of  the process heap supplied by the system.  It frees the memory space pointed to by ptr, which
       must have been returned by a previous call to pmemcto_malloc(), pmemcto_calloc() or pmemcto_realloc() for
       the same pool of memory.  Undefined behavior occurs if frees do not correspond to allocated  memory  from
       the same memory pool.  If ptr is NULL, no operation is performed.

       The  pmemcto_calloc()  function provides the same semantics as calloc(3), but operates on the memory pool
       pcp instead of the process heap supplied by the system.  It allocates memory for an array of  nmemb  ele‐
       ments  of  size bytes each and returns a pointer to the allocated memory.  The memory is set to zero.  If
       nmemb or size is 0, then pmemcto_calloc() returns either NULL, or a unique pointer value that  can  later
       be successfully passed to pmemcto_free().

       The pmemcto_realloc() function provides the same semantics as realloc(3), but operates on the memory pool
       pcp  instead of the process heap supplied by the system.  It changes the size of the memory block pointed
       to by ptr to size bytes.  The contents will be unchanged in the range from the start of the region up  to
       the minimum of the old and new sizes.  If the new size is larger than the old size, the added memory will
       not  be  initialized.   If ptr is NULL, then the call is equivalent to pmemcto_malloc(pcp, size), for all
       values of size; if size is equal to zero and ptr is not NULL, then  the  call  is  equivalent  to  pmemc‐
       to_free(pcp,  ptr).   Unless  ptr  is NULL, it must have been returned by an earlier call to pmemcto_mal‐
       loc(), pmemcto_calloc(), pmemcto_realloc() or pmemcto_aligned_alloc(3).   If  the  area  pointed  to  was
       moved, a pmemcto_free(pcp, ptr) is done.

RETURN VALUE

       On success, pmemcto_malloc() and pmemcto_calloc() functions return a pointer to the allocated memory.  If
       the allocation request cannot be satisfied, a NULL pointer is returned and errno is set appropriately.

       The pmemcto_free() function returns no value.

       On  success, pmemcto_realloc() function returns a pointer to the newly allocated memory, or NULL if it is
       unable to satisfy the allocation request.  If size was equal to 0, either NULL or a pointer  suitable  to
       be  passed  to  pmemcto_free()  is  returned.   If pmemcto_realloc() fails the original block is left un‐
       touched; it is not freed or moved.

ERRORS

       ENOMEM Insufficient memory available to satisfy allocation request.

NOTES

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

SEE ALSO

       jemalloc(3), malloc(3), pmemcto_aligned_alloc(3), libpmemcto(7) and <http://pmem.io>

PMDK - libpmemcto API version 1.0                  2018-05-21                                  PMEMCTO_MALLOC(3)