malloc() — Reserve Storage Block
Format
#include <stdlib.h>
void *malloc(size_t size);
Language Level
ANSI
Threadsafe
Yes
Description
The malloc()
function
reserves a block of storage of size bytes.
Unlike the calloc()
function, malloc()
does
not initialize all elements to 0. The maximum size for a
non-teraspace malloc()
is
16711568 bytes.
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. You cannot 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.
- 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
malloc()
library function to_C_TS_malloc()
, its teraspace storage counterpart. The maximum amount of teraspace storage that can be allocated by each call to_C_TS_malloc()
is 2GB - 224, or 2147483424 bytes. If more than 2147483408 bytes are needed on a single request, call_C_TS_malloc64(unsigned long long int);
.For more information, see the ILE Concepts manual.
- For current statistics on the teraspace storage being used by
MI programs in an activation group, call the
_C_TS_malloc_info
function. This function returns information including total bytes, allocated bytes and blocks, unallocated bytes and blocks, requested bytes, pad bytes, and overhead bytes. To get more detailed information about the memory structures used by the_C_TS_malloc()
and_C_TS_malloc64()
functions, call the_C_TS_malloc_debug()
function. You can use the information this function returns to identify memory corruption problems. - If the Quick Pool memory manager has been enabled in the current activation group, then the storage is retrieved using Quick Pool memory manager. See _C_Quickpool_Init() — Initialize Quick Pool Memory Manager for more information.
Return Value
The malloc()
function
returns a pointer to the reserved space. The storage space to which
the return value points is suitably aligned for storage of any type
of object. The return value is NULL if not enough storage
is available, or if size was specified as
zero.
Example
This example prompts for the number
of array entries you want and then reserves enough space in storage
for the entries. If
malloc()
was
successful, the example assigns values to the entries and prints out
each entry; otherwise, it prints out an error. #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 = (long *) malloc( num * sizeof( long ))) != NULL )
{
for ( i = 0; i < num; ++i ) /* put values in array */
*index++ = i; /* using pointer notation */
for ( i = 0; i < num; ++i ) /* print the array out */
printf( "array[ %i ] = %i\n", i, array[i] );
}
else { /* malloc error */
perror( "Out of storage" );
abort();
}
}
/******************** Output should be similar to: **************
Enter the size of the array
array[ 0 ] = 0
array[ 1 ] = 1
array[ 2 ] = 2
array[ 3 ] = 3
array[ 4 ] = 4
*/
Related Information
- calloc() — Reserve and Initialize Storage
- _C_Quickpool_Debug() — Modify Quick Pool Memory Manager Characteristics
- _C_Quickpool_Init() — Initialize Quick Pool Memory Manager
- _C_Quickpool_Report() — Generate Quick Pool Memory Manager Report
- free() — Release Storage Blocks
- realloc() — Change Reserved Storage Block Size
- Heap Memory
- <stdlib.h>