2.8 memory allocation macros

These macros use the standard ANSI/ISO C functions calloc(), realloc(), free(), strlen(), and strcpy() to handle dynamic memory allocation tasks for the WFDB library. They can also be used by applications that include ‘wfdb/wfdb.h’, where they are defined.

These macros provide safe handling of insufficient memory and double free errors (either condition results in a descriptive error message, which by default is followed by an exit(1) to end the process with a signal to the parent shell or other process).

MEMERR

MEMERR(object_name, size_t n_elements, size_t element_size)

This macro uses wfdb_error to send a short error message of the form WFDB: can't allocate (n_elements*element_size ) bytes for object_name). Unless wfdbmemerr(1) has been invoked previously, the process that invoked MEMERR exits immediately.

SFREE

SFREE(object *pointer)

This macro releases memory previously allocated to the object addressed by the specified pointer, somewhat more safely than by invoking the standard free() function. On completion, pointer is set to NULL.

SFREE does nothing if pointer is initially NULL (unlike free(), which may cause the process to crash). If SFREE receives a non-NULL pointer, it passes that pointer to free(), which may cause a crash if the pointer does not point to a block of memory that was previously allocated using one of the macros below, or directly using malloc(), calloc(), or realloc().

SUALLOC

SUALLOC(object_name, size_t n_elements, size_t element_size)

This macro allocates memory sufficient for n_elements items of element_size bytes each, and sets the pointer given by object_name to point to the allocated memory. If there is not enough available memory, SUALLOC invokes MEMERR (above).

The newly allocated memory block is filled with zeroes.

SUALLOC does not check to see if object_name already points to allocated memory, which will lead to memory leaks if so.

SALLOC

SALLOC(object_name, size_t n_elements, size_t element_size)

This macro allocates memory sufficient for n_elements items of element_size bytes each, and sets the pointer given by object_name to point to the allocated memory. If there is not enough available memory, SALLOC invokes MEMERR (above).

The newly allocated memory block is filled with zeroes.

Unless object_name is initially NULL, SALLOC frees it using SFREE before allocating the requested memory.

SREALLOC

SREALLOC(object_name, size_t n_elements, size_t element_size)

This macro allocates memory sufficient for n_elements items of element_size bytes each, and sets the pointer given by object_name to point to the allocated memory. If there is not enough available memory, SREALLOC invokes MEMERR (above).

Use SREALLOC to expand a previously allocated block of memory, preserving its contents. REALLOC usually allocates a new block of the desired size, moving the contents of the previously allocated block into the beginning of the new block and then freeing the original block. Pointers to locations in the original block will no longer be valid in this case.

The portion of the newly allocated block that extends beyond the previous contents is uninitialized.

If object_name is initially NULL, SUALLOC, SALLOC, and REALLOC are functionally equivalent, except that REALLOC does not fill the allocated block with zeroes.

SSTRCPY

SSTRCPY(char *destination, char *source)

This macro copies the source string (including a trailing null character) into newly-allocated memory, and it sets destination to point to the copy. If destination is not NULL on entry, SSTRCPY uses SFREE to release the previously allocated memory.