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 re-allocates 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.

The function returns NULL when the memory pointed to by old_blk cannot be re-allocated. 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, the realloc() function is equivalent to the _nrealloc() function; in a large data memory model, the realloc() function is equivalent to the _frealloc() function.

Returns:

The realloc() functions return a pointer to the start of the re-allocated memory. The return value is 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.

See also:

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

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:

Systems:

realloc()

All (except Netware, DOS/PM)

_brealloc()

DOS/16, Windows, QNX/16, OS/2 1.x(all)

_frealloc()

DOS/16, Windows, QNX/16, OS/2 1.x(all)

_nrealloc()

DOS, Windows, Win382, Win32, QNX, OS/2 1.x, OS/2 1.x(MT), OS2-32