Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File5.13.5  Mxalloc                                                    TOS

 Name:         »Allocate memory (with preference)« - Reserve memory 
               according to specified preferences.

 Opcode:       68

 Syntax:       void *Mxalloc ( int32_t amount, int16_t mode );

 Description:  The GEMDOS routine Mxalloc reserves a block of memory 
               of the size amount. One can use the bits of the WORD 
               parameter mode to specify the desired type of memory. 
               The following apply:

                Bits  Meaning

                0-2   Treatment of the TT-RAM
                       0 =  Allocate ST-RAM only
                       1 =  Allocate Alternative-RAM only
                       2 =  Allocate either, ST-RAM preferred
                       3 =  Allocate either, Alternative-RAM preferred
                3     Reserved
                4-7   Protection mode
                       0 =  Default (from your PRGFLAGS)
                       1 =  Private
                       2 =  Global
                       3 =  Supervisor-mode-only access
                       4 =  World-readable access
                      Other values are undefined and reserved.
                14    No-Free modus
                      When set, this bit means "if the owner of this 
                      block terminates, don't free this block. 
                      Instead, let MiNT inherit it, so it'll never be 
                      freed." This is a special mode meant for the OS 
                      only, and may not remain available to user 
                      processes.

               All further bits are reserved for future purposes. With 
               the value -1L for amount one can inquire the size of 
               the largest contiguous block of memory (dependent on 
               mode).

               Under MagiC all memory allocations are logged. If the 
               restriction set with LIMITMEM is exceeded, A NULL- 
               pointer will be returned. In the case amount = -1, the 
               minimum of free memory and not yet exhausted LIMITMEM 
               restriction will be returned. Exceptions are calls of 
               the screen manager (SCRENMGR) which controls the menus. 
               This ensures that even LIMITMEM-restricted programs do 
               not have problems with menu redraws.

               Note: A problem exists in ascertaining when the 
               extended modes (bits 3 and following) may be used. This 
               is because some older versions of GEMDOS do not get 
               along with these modes and are partly responsible for 
               crashing the application or the whole system. For this 
               reason many programmers test explicitly for the 
               presence of MiNT/MultiTOS or versions of MagiC >= 2.0. 
               Alternatively one can also use the function Mxmask.

 Return value: The function returns the start address of the reserved 
               block as an untyped pointer. Mxalloc returns a 0 when 
               insufficient memory is available.

 Availability: This function exists only from GEMDOS Version 0.19 on.

 Group:        Memory management

 See also:     Binding   Mfree   Malloc   Maddalt   Program flags