NAME

       vmem_malloc(),    vmem_calloc(),    vmem_realloc(),   vmem_free(),   vmem_aligned_alloc(),
       vmem_strdup(),  vmem_wcsdup(),  vmem_malloc_usable_size()  -  memory  allocation   related
       functions

SYNOPSIS

              #include <libvmem.h>

              void *vmem_malloc(VMEM *vmp, size_t size);
              void vmem_free(VMEM *vmp, void *ptr);
              void *vmem_calloc(VMEM *vmp, size_t nmemb, size_t size);
              void *vmem_realloc(VMEM *vmp, void *ptr, size_t size);
              void *vmem_aligned_alloc(VMEM *vmp, size_t alignment, size_t size);
              char *vmem_strdup(VMEM *vmp, const char *s);
              wchar_t *vmem_wcsdup(VMEM *vmp, const wchar_t *s);
              size_t vmem_malloc_usable_size(VMEM *vmp, void *ptr);

DESCRIPTION

       This  section  describes  the  malloc-like  API  provided  by libvmem(7).  These functions
       provide the same semantics as their libc  namesakes,  but  operate  on  the  memory  pools
       specified by their first arguments.

       The  vmem_malloc()  function provides the same semantics as malloc(3), but operates on the
       memory pool vmp instead of  the  process  heap  supplied  by  the  system.   It  allocates
       specified size bytes.

       The  vmem_free()  function  provides  the  same  semantics as free(3), but operates on the
       memory pool vmp 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
       vmem_malloc(), vmem_calloc() or vmem_realloc() for the same pool of  memory.   If  ptr  is
       NULL, no operation is performed.

       The  vmem_calloc()  function provides the same semantics as calloc(3), but operates on the
       memory pool vmp instead of the process heap supplied by the system.  It  allocates  memory
       for an array of nmemb elements of size bytes each.  The memory is set to zero.

       The vmem_realloc() function provides the same semantics as realloc(3), but operates on the
       memory pool vmp 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.

       Unless  ptr  is  NULL,  it  must  have  been returned by an earlier call to vmem_malloc(),
       vmem_calloc() or vmem_realloc().   If  ptr  is  NULL,  then  the  call  is  equivalent  to
       vmem_malloc(vmp,  size),  for all values of size; if size is equal to zero, and ptr is not
       NULL, then the call is equivalent to vmem_free(vmp, ptr).

       The vmem_aligned_alloc() function provides the same  semantics  as  aligned_alloc(3),  but
       operates  on  the  memory pool vmp instead of the process heap supplied by the system.  It
       allocates size bytes from the memory pool.  The memory  address  will  be  a  multiple  of
       alignment, which must be a power of two.

       The  vmem_strdup()  function provides the same semantics as strdup(3), but operates on the
       memory pool vmp instead of the process heap supplied by the system.  Memory  for  the  new
       string  is  obtained  with  vmem_malloc(), on the given memory pool, and can be freed with
       vmem_free() on the same memory pool.

       The vmem_wcsdup() function provides the same semantics as wcsdup(3), but operates  on  the
       memory  pool  vmp  instead of the process heap supplied by the system.  Memory for the new
       string is obtained with vmem_malloc(), on the given memory pool, and  can  be  freed  with
       vmem_free() on the same memory pool.

       The    vmem_malloc_usable_size()    function    provides    the    same    semantics    as
       malloc_usable_size(3), but operates on the memory pool vmp instead  of  the  process  heap
       supplied by the system.

RETURN VALUE

       On  success,  vmem_malloc() returns a pointer to the allocated memory.  If size is 0, then
       vmem_malloc()  returns  either  NULL,  or  a  unique  pointer  value  that  can  later  be
       successfully  passed to vmem_free().  If vmem_malloc() is unable to satisfy the allocation
       request, it returns NULL and sets errno appropriately.

       The vmem_free() function returns no value.  Undefined behavior  occurs  if  frees  do  not
       correspond to allocated memory from the same memory pool.

       On  success, vmem_calloc() returns a pointer to the allocated memory.  If nmemb or size is
       0, then vmem_calloc() returns either NULL, or a unique pointer value  that  can  later  be
       successfully  passed to vmem_free().  If vmem_calloc() is unable to satisfy the allocation
       request, it returns NULL and sets errno appropriately.

       On success, vmem_realloc() returns  a  pointer  to  the  allocted  memory,  which  may  be
       different  from ptr.  If the area pointed to was moved, a vmem_free(vmp, ptr) is done.  If
       vmem_realloc() is unable to satisfy the allocation request, it returns NULL and sets errno
       appropriately.

       On   success,  vmem_aligned_alloc()  returns  a  pointer  to  the  allocated  memory.   If
       vmem_aligned_alloc() is unable to satisfy the allocation request, it returns NULL and sets
       errno appropriately.

       On  success,  vmem_strdup()  returns a pointer to a new string which is a duplicate of the
       string s.  If vmem_strdup() is unable to satisfy the allocation request, it  returns  NULL
       and sets errno appropriately.

       On  success,  vmem_wcsdup()  returns  a  pointer to a new wide character string which is a
       duplicate of the wide character string s.  If  vmem_wcsdup()  is  unable  to  satisfy  the
       allocation request, it returns NULL and sets errno appropriately.

       The  vmem_malloc_usable_size() function returns the number of usable bytes in the block of
       allocated memory pointed to  by  ptr,  a  pointer  to  a  block  of  memory  allocated  by
       vmem_malloc() or a related function.  If ptr is NULL, 0 is returned.

SEE ALSO

       calloc(3),  free(3),  malloc(3),  malloc_usable_size(3),  realloc(3), strdup(3), wcsdup(3)
       libvmem(7) and <http://pmem.io>