The storage allocation routines let you reserve, free, and reallocate blocks of storage. The include file malloc.h contains the declarations of these functions.
Reserves storage from the stack.
Reserves storage for an array.
Expands or contracts a block of storage without moving its location.
Frees a block reserved by _fmalloc.
Reserves a block of storage outside the default data segment, returns a far pointer.
Frees a reserved block.
Returns the approximate number of items of a given size that the compiler can reserve.
Returns the size of a storage block pointed to by a far pointer.
Reserves a huge array.
Frees a block reserved by halloc.
Reserves a block.
Reports the approximate number of bytes available for reserving in the heap in memory.
Returns the size of the block reserved by calloc, malloc, or realloc.
Frees a block reserved by _nmalloc.
Reserves a block of storage in the default data segment, returns a near pointer.
Returns the size of a storage block pointed to by a near pointer.
Changes the size of a previously reserved block of storage.
Resets the break val ue.
Returns the size of the stack space available for reserve with alloca.
The calloc and malloc routines reserve storage blocks. The malloc routine reserves a given number of bytes; the calloc routine reserves and initializes to 0 an array with elements of a given size. The
rou-tines _fmalloe and _nmalloe are similar to malloe, except that _fmalloe and _nmalloe let you reserve blocks of bytes while over-coming the addressing limitations of the current storage model. The halloe routine performs essentially the same function as ealloe, with the difference that halloe reserves space for huge arrays (those exceeding 64K bytes in size). Arrays allocated with halloe must satisfy the requirements for huge arrays, as outlined in "Creating Huge Model Programs" in the IBM C/2 Compile, Link, and Run book.
The realloe and _expand routines change the size of an allocated block. The _expand function always attempts to change the size of an allocated block without moving its heap location. It expands the size of the block up to the size requested or as much as the current location allows, whichever is smaller. In contrast, realloe changes the location in the heap if there is not enough room. The halloe routine returns a huge pointer, _fmalloe returns a far pointer, and _nmalloe returns a near pointer. These routines all return a pointer to void; the space to which they point satisfies the alignment require-ments for any type of object. Use a type cast on the return value to obtain the type of pointer you need.
When _fmalloe is called it allocates a segment from DOS, returns the requested amount of memory, and does heap management on the rest for subsequent calls to _fmalloe. When it runs out of memory on its current segment, it goes to DOS for another. While _fmalloe allo-cates memory from DOS, _ffree returns it to _fmalloe's heap (the far heap). The _fmalloe routine attempts to allocate memory from the near heap in the default data segment as a last resort.
When an IBM C/2 program is loaded, it reduces its DOS allocated memory to:
program size
+
global and static variables+
stack+
heap area for _nmalloe,where variables
+
stack+
heap area <=64K.This overrides the specification in the program header which tells the loader to use all the memory. The extent to which the original allo-cation gets cut back is controlled by using the /CPARMAXALLOC link option described in Compile, Link, and Run.
The _nmalloe and _fmalloe routines exhibit performance differences.
allocation requirements are less than 64K. This amount is smaller depending on the number of external variables and the amount of runtime 1/0. _fmalloc is best when total memory allocation require-ments are greilter than 64K but no single data object is greater than 64K. The halloc function is the slowest of all because it petitions DOS
for every memory request. Select halloc as the function of choice when either you want data objects larger than 64K or you want to be certain you can free allocated memory back to DOS for subsequent program spawns.
The free routine (for calloc, malloc, and realloc), the _ffree routine (for _fmalloc), the _nfree routine (for _nmalloc), and the hfree routine (for halloc) all free storage that was previously reserved, making it available for later requests.
The _freect and _memavl routines tell you how much storage is avail-able for dynamic storage allocation in the default data segment. The _freect function returns the approximate number of items of a given size for which the compiler can reserve storage. The _memavl func-tion returns the total number of bytes available for allocafunc-tion requests.
The _msize function returns the size of a storage block reserved by a call to calloe, _expand, malloc, or realloc. The _fmsize and _nmsize functions return the size of a block of storage reserved by _fmalloc or _nmalloc, respectively.
The sbrk routine is a low-level routine that reserves storage. It increases the break value of the program, letting the program take advantage of available unreserved storage.
CAUTION:
A program that uses the sbrk routine should not use the other rou-tines that reserve storage although the compiler does not prohibit their use. Using sbrk to decrease the break value can cause later calls to other storage allocation routines to give unpredictable results.
The preceding routines all reserve storage dynamically from the heap. IBM C/2 also pr~vides two storage functions, alloca and stackavail, for reserving space from the stack and determining the amount of available stack space. The alloca function reserves, from
the stack, the requested number of bytes that the compiler frees when control returns from the function calling alloca. The stackavail func-tion lets your program know how much storage (in bytes) is available on the stack.