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 elements 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
       pmemcto_free(pcp, ptr).  Unless ptr is NULL, it must have been returned by an earlier call
       to pmemcto_malloc(), 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 untouched; 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>