libstddjb
skalibs
Software
www.skarnet.org

The alloc library interface

The following functions are declared in the alloc.h header, and implemented in the libstddjb.a or libstddjb.so library.

General information

alloc is the skalibs heap memory manager. It's actually a wrapper for the malloc() series of functions; it unifies a few system-dependent malloc behaviours. It's also the API to implement and preload if for some reason you need to plug in your own allocator: replacing alloc() is much easier than replacing malloc() safely.

As a general rule, you should not be using the alloc interface directly. Allocating and freeing individual cells in the heap is a recipe for heap fragmentation, as well as cell tracking nightmares leading to memory leaks. You should use the higher-level stralloc and genalloc interfaces to handle dynamic arrays of objects.

C's lack of automatic management of heap memory is not a drawback: it's a feature of the language. It allows for code that is one or two orders of magnitude faster than the equivalent in a higher-level language, and very low on resources consumption. However, it requires more attention from the programmer. Good APIs can significantly reduce the difficulty of keeping track of every heap-allocated cell, and every smart programmer should favor them over basic interfaces like malloc().

alloc is used internally by skalibs to implement stralloc, and nowhere else.

Functions

char *alloc (unsigned int len)
Allocates a block of len bytes in the heap and returns a pointer to the start of the block (or NULL if it failed). Though the pointer type is char *, the block of memory is correctly aligned for any type of object. If len is 0, the function returns a pointer that cannot be written to, but that is not null. Note that this is different from the required C99 behaviour for malloc().

void alloc_free (void *p)
Frees the block of heap memory pointed to by p.

int alloc_realloc (char **p, unsigned int newlen)
Redimension the block of heap memory pointed to by *p to newlen bytes. The block may have to be moved, in which case *p will be modified. Normally returns 1; if an error occurred, returns 0 and sets errno, and neither *p nor its contents are modified.

int alloc_re (char **p, unsigned int oldlen, unsigned int newlen)
Legacy interface for reallocation. It works like alloc_realloc, except that the original block length must be provided as the oldlen argument.