Memory management

Macros
#define	MALLOC(size)
	Allocate memory. More...
#define	MALLOC_ZEROED(size)
	Allocate memory and clear it to zeroes. More...
#define	MEMALIGN(align_size, requested_size)
	Allocate memory with alignment. More...
#define	REALLOC(addr, newSize)
	Re-allocate memory and copy original into it. More...
#define	STRDUP(string)
	Allocate memory and copy a string into it. More...
#define	STRNDUP(string, n)
	Allocate memory and copy a string into it, up to a limit. More...

Functions
void	ltrx_free (void *addr)
	Free previously allocated memory. More...
bool	ltrx_malloc_has_ever_failed (void)
	Determine if any memory allocation has yet failed. More...

Detailed Description

Memory may be dynamically allocated from the heap.

DO NOT call malloc(), calloc(), strdup(), strndup(), realloc(), or free(); your module will not build correctly. Instead see the functions and macros defined in this section.

Macro Definition Documentation

#define MALLOC

(

size

)

Value:

ltrx_malloc_do_not_call_directly( \
    size, __FILE__, __LINE__ \
)

Allocate memory.

This macro allocates size bytes. The memory is not initialized.

Parameters

[in]

size

Desired size in bytes.

Returns

Pointer to allocated memory.

Return values

NULL	MALLOC failed.

#define MALLOC_ZEROED

(

size

)

Value:

ltrx_malloc_zeroed_do_not_call_directly( \
    size, __FILE__, __LINE__ \
)

Allocate memory and clear it to zeroes.

This function allocates size bytes. The memory is initialized to zeroes.

Parameters

[in]

size

Desired size in bytes.

Returns

Pointer to allocated memory.

Return values

NULL	MALLOC_ZEROED failed.

#define MEMALIGN	(		align_size,
			requested_size
	)

Value:

ltrx_memalign_do_not_call_directly( \
    align_size, requested_size, __FILE__, __LINE__ \
)

Allocate memory with alignment.

This macro allocates requested_size bytes with align_size alignment. The memory is not initialized.

Parameters

[in]	align_size	Desired alignment; must be a power of two.
[in]	requested_size	Desired size in bytes.

Returns

Pointer to allocated memory.

Return values

NULL	MEMALIGN failed.

#define REALLOC	(		addr,
			newSize
	)

Value:

ltrx_realloc_do_not_call_directly( \
    addr, newSize, __FILE__, __LINE__ \
)

Re-allocate memory and copy original into it.

This function changes the size of the memory block pointed to by addr to newSize 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, the added memory will not be initialized. If addr is NULL, then the call is equivalent to MALLOC(newSize), for all values of newSize; if newSize is equal to zero and addr is not NULL, then the call is equivalent to ltrx_free(addr). Unless addr is NULL, it must have been returned by an earlier call to MALLOC(), MALLOC_ZEROED(), STRDUP(), STRNDUP(), or REALLOC(). If the area pointed to was moved, an ltrx_free(addr) is done.

Parameters

[in]	addr	Pointer to old allocated memory.
[in]	newSize	Desired new size in bytes.

Returns

Pointer to allocated memory.

Return values

NULL	REALLOC failed.

#define STRDUP

(

string

)

Value:

ltrx_strdup_do_not_call_directly( \
    string, __FILE__, __LINE__ \
)

Allocate memory and copy a string into it.

This function returns a pointer to a new string which is a duplicate of the input string.

Parameters

[in]

string

String to be duplicated.

Returns

Pointer to allocated memory.

Return values

NULL	STRDUP failed.

#define STRNDUP	(		string,
			n
	)

Value:

ltrx_strndup_do_not_call_directly( \
    string, n, __FILE__, __LINE__ \
)

Allocate memory and copy a string into it, up to a limit.

This function is similar to STRDUP(), but only copies at most n bytes. If string is longer than n, only n bytes are copied, and a terminating zero byte is added.

Parameters

[in]	string	String to be duplicated.
[in]	n	Maximum bytes to duplicate.

Returns

Pointer to allocated memory.

Return values

NULL	STRNDUP failed.

Function Documentation

void ltrx_free

(

void *

addr

)

Free previously allocated memory.

This function frees the memory space pointed to by addr, which must have been returned by a previous call to MALLOC(), MALLOC_ZEROED(), MEMALIGN(), STRDUP(), STRNDUP(), or REALLOC(). Otherwise, or if ltrx_free(addr) has already been called before, undefined behavior occurs. If addr is NULL, no operation is performed.

Parameters

[in]

addr

Previously allocated memory.

bool ltrx_malloc_has_ever_failed

(

void

)

Determine if any memory allocation has yet failed.

Return values

true	One or more allocation attempts have failed since bootup.
false	Memory allocation has not yet failed.