realloc(), _brealloc(), _frealloc(), _nrealloc()

allocate, reallocate or free a block of memory

Synopsis:

#include <stdlib.h>  /* For ANSI compatibility 
                        (realloc only) */
#include <malloc.h>  /* Required for other 
                        function prototypes */

void * realloc( void *old_blk, size_t size );
void __based(void) *_brealloc( __segment seg,
                     void __based(void) *old_blk,
                     size_t size );
void __far  *_frealloc( void __far  *old_blk,
                        size_t size );
void __near *_nrealloc( void __near *old_blk,
                        size_t size );

Description:

When the value of the old_blk argument is NULL, a new block of memory of size bytes is allocated.

If the value of size is zero, the corresponding free() function is called to release the memory pointed to by old_blk.

Otherwise, the realloc() function reallocates space for an object of size bytes by doing one of the following:

• shrinking the allocated size of the allocated memory block old_blk when size is sufficiently smaller than the 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, and copying the contents of old_blk to the new block.

Because it is possible that a new block will be allocated, any pointers into the old memory should not be maintained. These pointers will point to freed memory, with possible disastrous results, when a new block is allocated.

The function returns NULL when the memory pointed to by old_blk cannot be reallocated. In this case, the memory pointed to by old_blk is not freed, so care should be exercised to maintain a pointer to the old memory block.

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

In the above example, buffer will be set to NULL if the function fails, and will no longer point to the old memory block. If buffer is your only pointer to the memory block, then you'll have lost access to this memory.

Each function reallocates memory from a particular heap, as listed below:

realloc()

Depends on data model of the program (see below)

_brealloc()

Based heap specified by seg value

_frealloc()

Far heap (outside the default data segment)

_nrealloc()

Near heap (inside the default data segment)

In a small data memory model, realloc() is equivalent to _nrealloc(); in a large data memory model, realloc() is equivalent to _frealloc().

Returns:

A pointer to the start of the reallocated memory, or NULL if there is insufficient memory available, or if the value of the size argument is zero. The _brealloc() function returns _NULLOFF if there is insufficient memory available, or if the requested size is zero.

Examples:

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

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

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

      /* not able to allocate larger buffer */

    } else {
      buffer = new_buffer;
    }
  }

Classification:

See also:

calloc(), _expand(), free(), halloc(), hfree(), malloc(), _msize(), sbrk()