realloc()

Allocate, reallocate, or free a block of memory

Synopsis:

#include <stdlib.h>

void* realloc( void* old_blk, 
               size_t size );

Arguments:

old_blk: A pointer to the block of memory to be allocated, reallocated, or freed.
size: The new size, in bytes, for the block of memory.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The realloc() function allocates, reallocates, or frees the block of memory specified by old_blk based on the following rules. You can control parts of this behavior via the MALLOC_OPTIONS environmental variable.

If old_blk is NULL and size isn't 0, realloc() allocates a new block of memory of size bytes.
If old_blk is NULL and size is 0, the default behavior is to return a non-NULL pointer that's valid only to a corresponding call to free() or realloc(). Don't assume that this pointer points to any valid memory. If the value of MALLOC_OPTIONS contains a V, realloc() returns a NULL pointer. This environment variable also affects calloc() and malloc(). This is known as the "System V" behavior.
If old_blk is non-NULL and size is 0, the default behavior is to return a valid non-NULL pointer that's valid only to a corresponding call to free() or realloc(). Don't assume that this pointer points to any valid memory.
Note: The default behavior in this case changed in QNX Neutrino 6.4.1.

If the value of MALLOC_OPTIONS contains an R or a V, realloc() calls free() to release the memory pointed to by old_blk, and then returns NULL. This is the way QNX Neutrino 6.4.0 and earlier behaved.
Otherwise, realloc() reallocates space for an object of size bytes by:
- shrinking the size of the allocated memory block old_blk when size is smaller than the current size of old_blk
- extending the allocated size of the allocated memory block old_blk if there is a large enough block of unallocated memory immediately following old_blk
- allocating a new block with the appropriate size, and copying the contents of old_blk to this new block

The realloc() function allocates memory from the heap. Use free() or realloc() to free the block of memory.

Note:

The malloc() implementation uses signed, 32-bit integers to represent the size internally, so you can't allocate more than 2 GB in a single allocation. If the size is greater than 2 GB, realloc() indicates an error of ENOMEM.
Because it's possible that a new block will be allocated, any pointers into the old memory could be invalidated. These pointers will point to freed memory, with possible disastrous results, when a new block is allocated.

The realloc() function returns NULL when the memory pointed to by old_blk can't be reallocated. In this case, the memory pointed to by old_blk isn't freed, so be careful to maintain a pointer to the old memory block so you can free it later.

In the following example, buffer is set to NULL if the function fails, and won't point to the old memory block. If buffer is your only pointer to the memory block, then you have lost access to this memory.

buffer = (char* )realloc( buffer, 100 );

Returns:

A pointer to the start of the allocated memory, or NULL if an error occurred (errno is set).

Errors:

ENOMEM: Not enough memory.
EOK: No error.

Examples:

#include <stdlib.h>
#include <malloc.h>

int main( void )
{
    char* buffer;
    char* new_buffer;

    buffer = (char* )malloc( 80 );
    if ( buffer == NULL ) {
        return EXIT_FAILURE;
    }

    new_buffer = (char* )realloc( buffer, 100 );
    if( new_buffer == NULL ) {

        /* Couldn't allocate a larger buffer.
           Remember that buffer stills point to
           allocated memory -- don't leak it! */

        free (buffer);
        return EXIT_FAILURE;
    } else {
      buffer = new_buffer;
    }

    return EXIT_SUCCESS;
}

Environment variables:

MALLOC_OPTIONS

Control the way calloc(), malloc(), and realloc() behave if you specify a size of 0 (or a value of 0 for the n argument to calloc()). The V ("System V") and R ("use the realloc() behavior of QNX Neutrino 6.4.0 and earlier") columns below indicate how the functions behave if the value of MALLOC_OPTIONS includes that letter:

Function	Default	`V`	`R`
calloc(n, 0)	Non-NULL	NULL	No effect
malloc(0)	Non-NULL	NULL	No effect
realloc(NULL, 0)	Non-NULL	NULL	No effect
realloc(non-NULL, 0)	Non-NULL	NULL	NULL

In all the above cases, if the function returns a non-NULL pointer, it's valid only for a corresponding call to free() or realloc().

Classification:

ANSI, POSIX 1003.1

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes