Atari ST series Technical Reference Manual page 104

use of the Super() function may be found in the sample pro­
gram TOGGLE. S, below.
Memory Management Functions
The management of free memory is another common system
function made easier by the DOS commands. When a GEM
or TOS application program is first loaded and run, it takes
control of the entire application RAM space. As you will see
below, however, it may want to give back some of that mem­
ory so that other applications, desk accessories, or resident
programs may use it. Because an application can never know
how much free memory will be available, or where that free
memory is, the proper way to gain access to additional mem­
ory space is through the system memory manager. When a
program wants a hunk of free memory in which to store data
the user has input, or that it has retrieved from a disk file, it
requests the memory manager to allocate a certain number of
bytes. If that amount of memory is available, the memory
manager removes it from the free list and passes its starting
address to the application. When the application is finished
with the memory, it tells the memory manager, which re­
turns it to the free pool.
The GEMDOS function used to allocate free memory is
known by the macro name Malloc(). This function is called
as follows:
long address, bytes;
address = Malloc(bytes);
where bytes specifies the number of bytes of memory to allo­
cate. If bytes is set to - 1L (OxFFFFFFFF), the function simply
returns the size of the largest block of free memory in ad­
dress. Otherwise, the function tries to allocate the amount of
memory specified. If it is able to allocate the requested mem­
ory block, it returns the starting address of the block in ad­
dress. If there isn't sufficient free memory to allocate the
block that was requested, a value of 0 is returned instead.
When the program is finished using the memory it has
allocated, it should return it to the system by using the
M free() call
int status;
long address;
status = Mfree(address);
96
CHAPTER 5