free() — Release Storage Blocks

Format

#include <stdlib.h>
void free(void *ptr);

Language Level

ANSI

Threadsafe

Yes

Description

The free() function frees a block of storage. The ptr argument points to a block that is previously reserved with a call to the calloc(), malloc(), realloc(), _C_TS_calloc(), _C_TS_malloc(), _C_TS_realloc(), or _C_TS_malloc64() functions. The number of bytes freed is the number of bytes specified when you reserved (or reallocated, in the case of the realloc() function) the block of storage. If ptr is NULL, free() simply returns.

Note:

All heap storage is associated with the activation group of the calling function. As such, storage should be allocated, deallocated, and reallocated within the same activation group. It is not valid to allocate heap storage within one activation group and deallocate or reallocate that storage from a different activation group. For more information about activation groups, see the ILE Concepts manual.
Attempting to free a block of storage not allocated with calloc(), malloc(), or realloc() (or previously freed storage) can affect the subsequent reserving of storage and lead to undefined results. Storage that is allocated with the ILE bindable API CEEGTST can be freed with free().

To use teraspace storage instead of single-level store storage without changing the C source code, specify the TERASPACE(*YES *TSIFC) parameter on the compiler command. This maps the free() library function to _C_TS_free(), its teraspace storage counterpart.

Note: If a C2M1211 or C2M1212 message is generated from the free() function, refer to Diagnosing C2M1211/C2M1212 Message Problems for more information.

Return Value

There is no return value.

Example

This example uses the calloc() function to allocate storage for x array elements, and then calls the free() function to free them.

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
  long * array;    /* start of the array             */
  long * index;    /* index variable                 */
  int    i;        /* index variable                 */
  int  num;        /* number of entries of the array */
 
  printf( "Enter the size of the array\n" );
  scanf( "%i", &num );
 
  /* allocate num entries */
  if ( (index = array = calloc( num, sizeof( long ))) != NULL )
  {
    for ( i = 0; i < num; ++i )           /* put values in array    */
       *index++ = i;                      /* using pointer notation */
 
    free( array );                        /* deallocates array      */
  }
  else
  { /* Out of storage */
    perror( "Error: out of storage" );
    abort();
  }
}