realloc() — Change reserved storage block size

Format

#include <stdlib.h>

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

General Description

The realloc() function changes the size of a previously reserved storage block. The ptr argument points to the beginning of the block. The size argument gives the new size of the block in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes.

If the ptr is NULL, realloc() reserves a block of storage of size bytes. It does not give all bits of each element an initial value of 0.

If size is 0 and ptr is not NULL, the storage pointed to by ptr is freed and NULL is returned.

If you use realloc() with a pointer that does not point to a ptr created previously by malloc(), calloc(), or realloc(), or if you pass ptr to storage already freed, you get undefined behavior—typically an exception.

If you ask for more storage, the contents of the extension are undefined and are not guaranteed to be 0.

The storage to which the returned value points is aligned for storage of any type of object.

Note: Use of realloc() requires that an environment has been set up by using the __cinit() function. When the function is called, GPR 12 must contain the environment token created by the __cinit() call.

Returned Value

If successful, realloc() returns a pointer to the reallocated storage block. The storage location of the block might be moved. Thus, the returned value is not necessarily the same as the ptr argument to realloc().

The returned value is NULL if size is 0. If there is not enough storage to expand the block to the given size, the original block is unchanged and a NULL pointer is returned.

Related Information