Atari ST series Technical Reference Manual page 106

This diagram shows that the memory area not actually
used by the program is divided between the stack and the
heap. The stack is a temporary storage area used by pro­
grams for passing parameters, saving register contents, and
saving subroutine return addresses. The heap is the free
memory pool from which Malloc() doles out memory blocks.
The stack starts at the top of free memory and works its way
down, while the heap starts at the bottom of free memory
and works its way up.
Most programs don't need to retain control of all free
memory. They only need enough heap space for the Mal-
lo c() calls they make, and enough stack space to cover tem­
porary storage needs. The rest may be returned to the sys­
tem pool of free memory. Good programming practices
dictate that your program only retain control of the memory
it needs. In addition, there are a couple of specific reasons
for returning extra memory. If your program uses any of the
GEM library calls, it should return at least 8K of memory for
use by GEM. If your program uses the Pexec() function to
run another program (see below), there must be sufficient
free memory for that other program and its data.
The function used to shrink a program's memory block
is called Mshrink(), and it's called like this:
int status;
long address, size;
status = Mshrink(0, address, size);
where address is the starting address of the memory block to
retain, and size is the number of bytes to retain. Note that
you must pass a 0, 16 bits in length, as the first parameter. If
the operation is successful, a value of 0 is returned in status.
If it is unsuccessful, an error code of - 40 (invalid memory
block address) or - 67 (memory block growth failure) will be
returned.
To use Mshrink(), determine where the starting address
of program memory is, and how much memory the program
occupies. Finding the starting address of program memory
isn't too difficult—when you start a program, the second
word on the stack points to that location.
Finding the size of the program requires a little more
knowledge of how program storage space is allocated. As
mentioned above, the memory area in which a program re­
sides is known as the Transient Program Area (TPA), and at
98
CHAPTER 5