11.3.5 System support functions

New(bytes)

Returns a pointer to a newly allocated chunk of memory, which is bytes number of bytes. If the memory could not be allocated NIL is returned. The memory is initialised to zero in each byte, and taken from any available store (Fast or Chip memory, in that order of preference). When you've finished with this memory you can use Dispose to free it for use elsewhere in your program. You don't have to Dispose with memory you allocated with New because your program will automatically free it when it terminates. This is not true for memory allocated using the normal Amiga system routines.

NewR(bytes)

The same as New except that if the memory could not be allocated then the exception "MEM" is raised (and so, in this case, the function does not return). See 13 Exception Handling.

NewM(bytes,type)

The same as NewR except that the type of memory (Fast or Chip) to be allocated can be specified using flags. The flags are defined in the module `exec/memory' (see 12.2 Amiga System Modules). See the Rom Kernel Reference Manual (Libraries) for details about the system function AllocMem which uses these flags in the same way.

As useful example, here's a small program which allocates some cleared (i.e., zeroed) Chip memory.

MODULE 'exec/memory'

PROC main()
  DEF m
  m:=NewM(20, MEMF_CHIP OR MEMF_CLEAR)
  WriteF('Allocation succeeded, m = $\h\n', m)
EXCEPT
  IF exception="NEW" THEN WriteF('Failed\n')
ENDPROC

Dispose(address)

Used to free memory allocated with New, NewR or NewM. You should rarely need to use this function because the memory is automatically freed when the program terminates.

DisposeLink(complex)

Used to free the memory allocated with String (see 9.5.2 String functions) or List (see 9.5.4 List functions). Again, you should rarely need to use this function because the memory is automatically freed when the program terminates.

FastNew(bytes)

The same as NewR except it uses a very fast, recycling method of allocating memory. The memory allocated using FastNew is, as ever, deallocated automatically at the end of a program, and can be deallocated before then using FastDispose. Note that only FastDispose can be used and that it differs slightly from the Dispose and DisposeLink functions (you have to specify the number of bytes again when deallocating).

FastDispose(address,bytes)

Used to free the memory allocated using FastNew. The bytes parameter must be the same as the bytes used when the memory was allocated with FastNew, but the benefit is much faster allocation and deallocation, and generally more efficient use of memory.

CleanUp(expression=0)

Terminates the program at this point, and does the normal things an E program does when it finishes. The value denoted by expression is returned as the error code for the program. It is the replacement for the AmigaDOS Exit routine which should never be used in an E program. This is the only safe way of terminating a program, other than reaching the (logical) end of the main procedure (which is by far the most common way!).

CtrlC()

Returns TRUE if control-C has been pressed since the last call, and FALSE otherwise. This is really sensible only for programs started from the Shell/CLI.

FreeStack()

Returns the current amount of free stack space for the program. Only complicated programs need worry about things like stack. Recursion is the main thing that eats a lot of stack space (see 16 Recursion).

KickVersion(expression)

Returns TRUE if your Kickstart revision is at least that given by expression, and FALSE otherwise. For instance, KickVersion(37) checks whether you're running with Kickstart version 37 or greater (i.e., AmigaDOS 2.04 and above).

Go to the Next or Previous section, the Detailed Contents, or the Amiga E Encyclopedia.