NAME

mops.c - basic memory operation

Version Tag $Id: mops.c,v 1.19 2006/02/06 19:55:46 db60 Exp $


alloc - ALLOCATE DYNAMIC HEAP MEMORY

SYNOPSIS

void *alloc(const size_t bytes, const char *const msg);

DESCRIPTION

alloc is a wrapper for the standard library function malloc. It allocates new memory, or, on failure, crashes with an error message. It also assures a system-independent return value, NULL, if a zero-byte allocation is requested.

alloc will always fail without calling malloc if the request exceeds MAX_ALLOC bytes, where MAX_ALLOC is defined in lvb.h. This avoids straining malloc beyond typical use. MAX_ALLOC is a large number that will comfortably fit in a 32-bit signed integer.

The allocated memory may be freed with the standard library function free.

The new memory is not initialized.

PARAMETERS

INPUT

bytes

The number of bytes to allocate. If bytes is zero, no memory is allocated.

msg

Pointer to the first text character in a string that describes the object being allocated. On allocation failure, alloc will crash with an error message of 'FATAL ERROR: out of memory: cannot allocate for ', followed by this string.

RETURN

Returns pointer to the first byte of the newly allocated memory, which is suitably aligned for storage of any object, or NULL if a zero-byte allocation was requested.