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 allocated 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>