====
exec
====

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`AbortIO()`_                            `AddDevice()`_                          `AddHead()`_                            `AddIntServer()`_                       
`AddLibrary()`_                         `AddMemHandler()`_                      `AddMemList()`_                         `AddPort()`_                            
`AddResetCallback()`_                   `AddResource()`_                        `AddSemaphore()`_                       `AddTail()`_                            
`AddTask()`_                            `Alert()`_                              `AllocAbs()`_                           `Allocate()`_                           
`AllocEntry()`_                         `AllocMem()`_                           `AllocPooled()`_                        `AllocSignal()`_                        
`AllocTaskStorageSlot()`_               `AllocTrap()`_                          `AllocVec()`_                           `AllocVecPooled()`_                     
`AttemptSemaphore()`_                   `AttemptSemaphoreShared()`_             `AvailMem()`_                           `AVL_AddNode()`_                        
`AVL_FindFirstNode()`_                  `AVL_FindLastNode()`_                   `AVL_FindNextNodeByAddress()`_          `AVL_FindNextNodeByKey()`_              
`AVL_FindNode()`_                       `AVL_FindPrevNodeByAddress()`_          `AVL_FindPrevNodeByKey()`_              `AVL_RemNodeByAddress()`_               
`AVL_RemNodeByKey()`_                   `CacheClearE()`_                        `CacheClearU()`_                        `CacheControl()`_                       
`CachePostDMA()`_                       `CachePreDMA()`_                        `Cause()`_                              `CheckIO()`_                            
`ChildFree()`_                          `ChildOrphan()`_                        `ChildStatus()`_                        `ChildWait()`_                          
`CloseDevice()`_                        `CloseLibrary()`_                       `ColdReboot()`_                         `CopyMem()`_                            
`CopyMemQuick()`_                       `CreateIORequest()`_                    `CreateMsgPort()`_                      `CreatePool()`_                         
`Deallocate()`_                         `Debug()`_                              `DeleteIORequest()`_                    `DeleteMsgPort()`_                      
`DeletePool()`_                         `Disable()`_                            `Dispatch()`_                           `DoIO()`_                               
`Enable()`_                             `Enqueue()`_                            `Exec_FindChild()`_                     `ExitIntr()`_                           
`FindName()`_                           `FindPort()`_                           `FindResident()`_                       `FindSemaphore()`_                      
`FindTask()`_                           `FindTaskByPID()`_                      `Forbid()`_                             `FreeEntry()`_                          
`FreeMem()`_                            `FreePooled()`_                         `FreeSignal()`_                         `FreeTaskStorageSlot()`_                
`FreeTrap()`_                           `FreeVec()`_                            `FreeVecPooled()`_                      `GetCC()`_                              
`GetMsg()`_                             `GetParentTaskStorageSlot()`_           `GetTaskStorageSlot()`_                 `InitCode()`_                           
`InitResident()`_                       `InitSemaphore()`_                      `InitStruct()`_                         `Insert()`_                             
`MakeFunctions()`_                      `MakeLibrary()`_                        `NewAddTask()`_                         `NewAllocEntry()`_                      
`NewCreateTaskA()`_                     `NewMinList()`_                         `NewStackSwap()`_                       `ObtainQuickVector()`_                  
`ObtainSemaphoreList()`_                `ObtainSemaphoreShared()`_              `OldOpenLibrary()`_                     `OpenDevice()`_                         
`OpenLibrary()`_                        `OpenResource()`_                       `Permit()`_                             `Procure()`_                            
`PutMsg()`_                             `RawDoFmt()`_                           `ReadGayle()`_                          `ReleaseSemaphore()`_                   
`ReleaseSemaphoreList()`_               `RemDevice()`_                          `RemHead()`_                            `RemIntServer()`_                       
`RemLibrary()`_                         `RemMemHandler()`_                      `Remove()`_                             `RemPort()`_                            
`RemResetCallback()`_                   `RemResource()`_                        `RemSemaphore()`_                       `RemTail()`_                            
`RemTask()`_                            `ReplyMsg()`_                           `Reschedule()`_                         `RestoreTaskStorage()`_                 
`SaveTaskStorage()`_                    `Schedule()`_                           `SendIO()`_                             `SetExcept()`_                          
`SetFunction()`_                        `SetIntVector()`_                       `SetSignal()`_                          `SetSR()`_                              
`SetTaskPri()`_                         `SetTaskStorageSlot()`_                 `ShutdownA()`_                          `Signal()`_                             
`StackSwap()`_                          `SumKickData()`_                        `SumLibrary()`_                         `SuperState()`_                         
`Supervisor()`_                         `Switch()`_                             `TypeOfMem()`_                          `UserState()`_                          
`Vacate()`_                             `VNewRawDoFmt()`_                       `Wait()`_                               `WaitIO()`_                             
`WaitPort()`_                           
======================================= ======================================= ======================================= ======================================= 

-----------

AbortIO()
=========

Synopsis
~~~~~~~~
::

 LONG AbortIO(
          struct IORequest * iORequest );

Function
~~~~~~~~
::

     Calls the AbortIO vector of the appropriate device to stop an
     asynchronously started io request before completion. This may
     or may not be done. You still have to do a WaitIO() on the
     iorequest structure.


Inputs
~~~~~~
::

     iORequest - Pointer to iorequest structure.


Result
~~~~~~
::

     Errorcode if the abort request failed, 0 if the abort request went
     well. io_Error will then be set to IOERR_ABORTED.



See also
~~~~~~~~

`OpenDevice()`_ `CloseDevice()`_ `DoIO()`_ `SendIO()`_ `WaitIO()`_ 

----------

AddDevice()
===========

Synopsis
~~~~~~~~
::

 void AddDevice(
          struct Device * device );

Function
~~~~~~~~
::

     Adds a given device to the system's device list after checksumming
     the device vectors. This function is not for general use but
     (of course) for building devices that don't use exec's MakeLibrary()
     mechanism.


Inputs
~~~~~~
::

     device - Pointer to a ready for use device structure.



See also
~~~~~~~~

`RemDevice()`_ `OpenDevice()`_ `CloseDevice()`_ 

----------

AddHead()
=========

Synopsis
~~~~~~~~
::

 void AddHead(
          struct List * list,
          struct Node * node );

Function
~~~~~~~~
::

     Insert Node node as the first node of the list.


Inputs
~~~~~~
::

     list - The list to insert the node into
     node - This node is to be inserted


Result
~~~~~~
::

     None.


Example
~~~~~~~
::

     struct List * list;
     struct Node * pred;

     // Insert Node at top
     AddHead (list, node);



See also
~~~~~~~~

libamiga/NewList() `AddTail()`_ `Insert()`_ `Remove()`_ `RemHead()`_ `RemTail()`_ `Enqueue()`_ 

----------

AddIntServer()
==============

Synopsis
~~~~~~~~
::

 void AddIntServer(
          ULONG intNumber,
          struct Interrupt * interrupt );

Notes
~~~~~
::

     This function also enables the corresponding chipset interrupt if
     run on a native Amiga.



----------

AddLibrary()
============

Synopsis
~~~~~~~~
::

 void AddLibrary(
          struct Library * library );

Function
~~~~~~~~
::

     Adds a given library to the system's library list after checksumming
     the library vectors. This function is not for general use but
     (of course) for building shared libraries that don't use exec's
     MakeLibrary() mechanism.


Inputs
~~~~~~
::

     library - Pointer to a ready for use library structure.


Notes
~~~~~
::

     Some old Amiga software expects that AddLibrary returns the
     library which was just added. When in binary compatibility mode
     AROS does this too.



See also
~~~~~~~~

`RemLibrary()`_ `MakeLibrary()`_ `MakeFunctions()`_ `InitStruct()`_ `SumLibrary()`_ 

----------

AddMemHandler()
===============

Synopsis
~~~~~~~~
::

 void AddMemHandler(
          struct Interrupt * memHandler );

Function
~~~~~~~~
::

     Add some function to be called if the system is low on memory.


Inputs
~~~~~~
::

     memHandler - An Interrupt structure to add to the low memory
          handler list.



----------

AddMemList()
============

Synopsis
~~~~~~~~
::

 void AddMemList(
          IPTR size,
          ULONG attributes,
          LONG pri,
          APTR base,
          STRPTR name );

Function
~~~~~~~~
::

     Add a new block of memory to the system memory lists.


Inputs
~~~~~~
::

     size       - Size of the block
     attributes - The attributes the memory will have
     pri        - Priority in the list of MemHeaders
     base       - Base address
     name       - A name associated with the memory


Notes
~~~~~
::

     No argument checking done.



----------

AddPort()
=========

Synopsis
~~~~~~~~
::

 void AddPort(
          struct MsgPort * port );

Function
~~~~~~~~
::

     Add a port to the public port list. The ln_Name and ln_Pri fields
     must be initialized prior to calling this function, while
     the port itself is reinitialized before adding. Therefore it's
     not allowed to add an active port.


Inputs
~~~~~~
::

     port - Pointer to messageport structure.



----------

AddResetCallback()
==================

Synopsis
~~~~~~~~
::

 BOOL AddResetCallback(
          struct Interrupt * interrupt );

Function
~~~~~~~~
::

     Install a system reset notification callback. The callback
     will be called whenever system reboot is performed.

     The given Interrupt structure is inserted into the callback list
     according to its priority. The callback code is called with the same
     arguments as an interrupt server.


Inputs
~~~~~~
::

     interrupt - A pointer to an Interrupt structure


Result
~~~~~~
::

     TRUE for success, FALSE for failure


Notes
~~~~~
::

     This function is compatible with AmigaOS v4.



----------

AddResource()
=============

Synopsis
~~~~~~~~
::

 void AddResource(
          APTR resource );

Function
~~~~~~~~
::

     Adds a given resource to the system's resource list.


Inputs
~~~~~~
::

     resource - Pointer to a ready for use resource.



See also
~~~~~~~~

`RemResource()`_ `OpenResource()`_ 

----------

AddSemaphore()
==============

Synopsis
~~~~~~~~
::

 void AddSemaphore(
          struct SignalSemaphore * sigSem );

Function
~~~~~~~~
::

     Adds a semaphore to the system public semaphore list. Since the
     semaphore gets initialized by this function it must be free at
     this time. Also the ln_Name field must be set.


Inputs
~~~~~~
::

     sigSem - Pointer to semaphore structure


Notes
~~~~~
::

     Semaphores are shared between the tasks that use them and must
     therefore lie in public (or at least shared) memory.



----------

AddTail()
=========

Synopsis
~~~~~~~~
::

 void AddTail(
          struct List * list,
          struct Node * node );

Function
~~~~~~~~
::

     Insert Node node at the end of a list.


Inputs
~~~~~~
::

     list - The list to insert the node into
     node - This node is to be inserted


Example
~~~~~~~
::

     struct List * list;
     struct Node * pred;

     // Insert Node at end of the list
     AddTail (list, node);



----------

AddTask()
=========

Synopsis
~~~~~~~~
::

 APTR AddTask(
          struct Task * task,
          APTR initialPC,
          APTR finalPC );

Function
~~~~~~~~
::

     Add a new task to the system. If the new task has the highest
     priority of all and task switches are allowed it will be started
     immediately.

     You must initialise certain fields, and allocate a stack before
     calling this function. The fields that must be initialised are:
     tc_SPLower, tc_SPUpper, tc_SPReg, and the tc_Node structure.

     If any other fields are initialised to zero, then they will be
     filled in with the system defaults.

     The value of tc_SPReg will be used as the location for the stack
     pointer. You can place any arguments you wish to pass to the Task
     onto the stack before calling AddTask(). However note that you may
     need to consider the stack direction on your processor.

     Memory can be added to the tc_MemEntry list and will be freed when
     the task dies. The new task's registers are set to 0.


Inputs
~~~~~~
::

     task      - Pointer to task structure.
     initialPC - Entry point for the new task.
     finalPC   - Routine that is called if the initialPC() function
                 returns. A NULL pointer installs the default finalizer.


Result
~~~~~~
::

     The address of the new task or NULL if the operation failed.


Notes
~~~~~
::

     Use of AddTask() is deprecated on AROS; NewAddTask() should be used
     instead. AddTask() is only retained for backwards compatiblity.

     No proper initialization for alternative stack is done so alternative
     stack can't be in tasks started with AddTask(). This means that on
     some archs no shared library functions can be called.



See also
~~~~~~~~

`RemTask()`_ `NewAddTask()`_ 

----------

Alert()
=======

Synopsis
~~~~~~~~
::

 void Alert(
          ULONG alertNum );

Function
~~~~~~~~
::

     Alerts the user of a serious system problem.


Inputs
~~~~~~
::

     alertNum - This is a number which contains information about
             the reason for the call.


Result
~~~~~~
::

     This routine may return, if the alert is not a dead-end one.


Example
~~~~~~~
::

     // Dead-End alert: 680x0 Access To Odd Address
     Alert (0x80000003);


Notes
~~~~~
::

     You should not call this routine because it halts the machine,
     displays the message and then may reboot it.



----------

AllocAbs()
==========

Synopsis
~~~~~~~~
::

 APTR AllocAbs(
          IPTR byteSize,
          APTR location );

Function
~~~~~~~~
::

     Allocate some memory from the system memory pool at a given address.
     The memory must be freed with FreeMem().


Inputs
~~~~~~
::

     byteSize - Number of bytes you want to get
     location - Where you want to get the memory


Result
~~~~~~
::

     A pointer to some memory including the requested bytes or NULL if
     the memory couldn't be allocated.



See also
~~~~~~~~

`FreeMem()`_ 

----------

Allocate()
==========

Synopsis
~~~~~~~~
::

 APTR Allocate(
          struct MemHeader * freeList,
          IPTR byteSize );

Function
~~~~~~~~
::

     Allocate memory out of a private region handled by the MemHeader
     structure.


Inputs
~~~~~~
::

     freeList - Pointer to the MemHeader structure which holds the memory
     byteSize - Number of bytes you want to get


Result
~~~~~~
::

     A pointer to the number of bytes you wanted or NULL if the memory
     couldn't be allocated


Example
~~~~~~~
::

     #define POOLSIZE 4096
     \* Get a MemHeader structure and some private memory *\
     mh=(struct MemHeader *)
         AllocMem(sizeof(struct MemHeader)+POOLSIZE,MEMF_ANY);
     if(mh!=NULL)
     {
         \* Build a private pool *\
         mh->mh_First=(struct MemChunk *)(mh+1);
         mh->mh_First->mc_Next=NULL;
         mh->mh_First->mc_Bytes=POOLSIZE;
         mh->mh_Free=POOLSIZE;
         {
         \* Use the pool *\
         UBYTE *mem1,*mem2;
         mem1=Allocate(mh,1000);
         mem2=Allocate(mh,2000);
         \* Do something with memory... *\
         }
         \* Free everything at once *\
         FreeMem(mh,sizeof(struct MemHeader)+POOLSIZE);
     }


Notes
~~~~~
::

     The memory is aligned to sizeof(struct MemChunk). All requests
     are rounded up to a multiple of that size.


Bugs
~~~~
::

     Does not work with managed memory blocks because of backwards
     compatibility issues



See also
~~~~~~~~

`Deallocate()`_ 

----------

AllocEntry()
============

Synopsis
~~~~~~~~
::

 struct MemList * AllocEntry(
          struct MemList * entry );

Function
~~~~~~~~
::

     Allocate a number of memory blocks through a MemList structure.


Inputs
~~~~~~
::

     entry - The MemList with one MemEntry for each block you want to get


Result
~~~~~~
::

     The allocation was successful if the most significant bit of the
     result is 0. The result then contains a pointer to a copy of
     the MemList structure with the me_Addr fields filled.
     If the most significant bit is set the result contains the type of
     memory that couldn't be allocated.



See also
~~~~~~~~

`FreeEntry()`_ 

----------

AllocMem()
==========

Synopsis
~~~~~~~~
::

 APTR AllocMem(
          IPTR byteSize,
          ULONG requirements );

Function
~~~~~~~~
::

     Allocate some memory from the sytem memory pool with the given
     requirements.


Inputs
~~~~~~
::

     byteSize     - Number of bytes you want to get
     requirements - Type of memory


Result
~~~~~~
::

     A pointer to the number of bytes you wanted or NULL if the memory
     couldn't be allocated


Example
~~~~~~~
::

     mytask=(struct Task *)AllocMem(sizeof(struct Task),MEMF_PUBLIC|MEMF_CLEAR);


Notes
~~~~~
::

     The memory is aligned to sizeof(struct MemChunk). All requests
     are rounded up to a multiple of that size.



See also
~~~~~~~~

`FreeMem()`_ 

----------

AllocPooled()
=============

Synopsis
~~~~~~~~
::

 APTR AllocPooled(
          APTR poolHeader,
          IPTR memSize );

Function
~~~~~~~~
::

     Allocate memory out of a private memory pool. The memory must be
     freed with FreePooled(), or by deallocating the entire pool with
     DeletePool().


Inputs
~~~~~~
::

     poolHeader - Handle of the memory pool
     memSize    - Number of bytes you want to get


Result
~~~~~~
::

     A pointer to the number of bytes you wanted or NULL if the memory
     couldn't be allocated



See also
~~~~~~~~

`CreatePool()`_ `DeletePool()`_ `FreePooled()`_ 

----------

AllocSignal()
=============

Synopsis
~~~~~~~~
::

 BYTE AllocSignal(
          LONG signalNum );

Function
~~~~~~~~
::

     Allocate a given signal out of the current task's pool of signals.
     Every task has a set of signals to communicate with other tasks.
     Half of them are reserved for the system and half of them are
     free for general use. Some of the reserved signals (e.g.
     SIGBREAKF_CTRL_C) have a defined behaviour and may be used by user
     code, however.

     You must not allocate or free signals from exception handlers.


Inputs
~~~~~~
::

     signalNum - Number of the signal to allocate or -1 if any signal
                 will do.


Result
~~~~~~
::

     Number of the signal or -1 if the signal couldn't be allocated.



See also
~~~~~~~~

`FreeSignal()`_ `Signal()`_ `Wait()`_ 

----------

AllocTaskStorageSlot()
======================

Synopsis
~~~~~~~~
::

 LONG AllocTaskStorageSlot();

Function
~~~~~~~~
::

     This function will allocate a slot in the taskstorage.


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     slot - The allocated slot, or 0 if no slot could be allocated.


Notes
~~~~~
::

     After this function SetTaskStorageSlot(slot) may be used to store
     values with each slot.



See also
~~~~~~~~

`FreeTaskStorageSlot()`_ `GetTaskStorageSlot()`_ `SetTaskStorageSlot()`_ 

----------

AllocTrap()
===========

Synopsis
~~~~~~~~
::

 LONG AllocTrap(
          long trapNum );


----------

AllocVec()
==========

Synopsis
~~~~~~~~
::

 APTR AllocVec(
          IPTR byteSize,
          ULONG requirements );

Function
~~~~~~~~
::

     Allocate some memory from the sytem memory pool with the given
     requirements and without the need to memorize the actual size
     of the block.


Inputs
~~~~~~
::

     byteSize     - Number of bytes you want to get
     requirements - Type of memory


Result
~~~~~~
::

     A pointer to the number of bytes you wanted or NULL if the memory
     couldn't be allocated



See also
~~~~~~~~

`FreeVec()`_ 

----------

AllocVecPooled()
================

Synopsis
~~~~~~~~
::

 APTR AllocVecPooled(
          APTR poolHeader,
          IPTR memSize );

Function
~~~~~~~~
::

     Allocate memory out of a private memory pool and remember the size.
     The memory must be freed with FreeVecPooled(), or by deallocating
     the entire pool with DeletePool().


Inputs
~~~~~~
::

     poolHeader - Handle of the memory pool
     memSize    - Number of bytes you want to get


Result
~~~~~~
::

     A pointer to the number of bytes you wanted or NULL if the memory
     couldn't be allocated



See also
~~~~~~~~

`CreatePool()`_ `DeletePool()`_ `FreeVecPooled()`_ 

----------

AttemptSemaphore()
==================

Synopsis
~~~~~~~~
::

 ULONG AttemptSemaphore(
          struct SignalSemaphore * sigSem );

Function
~~~~~~~~
::

     Tries to get an exclusive lock on a signal semaphore. If the semaphore
     is already in use by another task, this function does not wait but
     returns false instead.


Inputs
~~~~~~
::

     sigSem - Pointer to semaphore structure.


Result
~~~~~~
::

     TRUE if the semaphore could be obtained, FALSE otherwise.


Notes
~~~~~
::

     The lock must be freed with ReleaseSemaphore().



See also
~~~~~~~~

`ReleaseSemaphore()`_ 

----------

AttemptSemaphoreShared()
========================

Synopsis
~~~~~~~~
::

 ULONG AttemptSemaphoreShared(
          struct SignalSemaphore * sigSem );

Function
~~~~~~~~
::

     Tries to get a shared lock on a signal semaphore. If the lock cannot
     be obtained false is returned. There may be more than one shared lock
     at a time but an exclusive lock prevents all other locks. The lock
     must be released with ReleaseSemaphore().


Inputs
~~~~~~
::

     sigSem - pointer to semaphore structure


Result
~~~~~~
::

     True if the semaphore could be obtained, false otherwise.



See also
~~~~~~~~

`ReleaseSemaphore()`_ 

----------

AvailMem()
==========

Synopsis
~~~~~~~~
::

 IPTR AvailMem(
          ULONG attributes );

Function
~~~~~~~~
::

     Return either the total available memory or the largest available
     chunk of a given type of memory.


Inputs
~~~~~~
::

     attributes - The same attributes you would give to AllocMem().


Result
~~~~~~
::

     Either the total of the available memory or the largest chunk if
     MEMF_LARGEST is set in the attributes.


Example
~~~~~~~
::

     Print the total available memory.

     printf("Free memory: %lu bytes\n", AvailMem(0));

     Print the size of the largest chunk of chip memory.

     printf("Largest chipmem chunk: %lu bytes\n",
            AvailMem(MEMF_CHIP | MEMF_LARGEST));


Notes
~~~~~
::

     Due to the nature of multitasking the returned value may already
     be obsolete when this function returns.



----------

AVL_AddNode()
=============

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_AddNode(
          struct AVLNode ** root,
          struct AVLNode * node,
          AVLNODECOMP func );

Function
~~~~~~~~
::

     Add a new node to an AVL tree.


Inputs
~~~~~~
::

     Root  - The root node of the tree to which the new node will be added.
             Initially and if the tree is empty, this will be NULL.

     Node  - The new node to add.  Any key information must alread be
             initialised.

     Func  - A key comparison function.  It will be passed 2 nodes,
             node1 and node2 to compare and must return <0, 0 or >0 to
             reflect node1 < node2, node1 == node, or node1 > node2
             respectively.


Result
~~~~~~
::

     NULL if the node was added to the tree, or a pointer to a node with the
     same key which already exists in the tree.


Example
~~~~~~~
::

     This is a fragment which counts the occurances of every word in a file.
     Also note that this example embeds the struct AVLNode data at
     the start of the structure, so simple casts suffice for translating
     AVLNode to ExampleNode addresses.

     struct ExampleNode {
         struct AVLNode avl;
         STRPTR key;
         ULONG count;
     };

     static LONG ExampleNodeComp(const struct AVLNode *a1, const struct AVLNode *a2)
     {
         const struct ExampleNode *e1 = (const struct ExampleNode *)a1;
         const struct ExampleNode *e2 = (const struct ExampleNode *)e2;

         return strcmp(a1->key, a2->key);
     }

     static LONG ExampleKeyComp(const struct AVLNode *a1, AVLKey key)
     {
         const struct ExampleNode *e1 = (const struct ExampleNode *)a1;
         char *skey = key;

         return strcmp(a1->key, skey);
     }

     void CountWords(wordfile)
     {
         struct ExampleNode *node;
         struct AVLNode *root = NULL, *check;

         node = AllocMem(sizeof(struct ExampleNode), 0);
         node->count = 1;

         while (node->key = read_word(wordfile)) {
             check = AVL_AddNode(&root, &node->avl, ExampleNodecomp);

             if (check != NULL) {
                 struct ExampleNode *work = (struct ExampleNode *)check;

                 check->count += 1;
             } else {
                 free(node->key);
                 node = AllocMem(sizeof(struct ExampleNode), 0);
                 node->count = 1;
             }
         }
         FreeMem(node, sizeof(struct ExampleNode));
     }


Notes
~~~~~
::

     AVL trees are balanced binary search trees.  This implementation is
     based on embedding the struct AVLNode within your own data object
     and providing custom comparison functions wherever they are needed.

     Two comparison functions are needed for different cases.  It is entirely
     up to the application as to how it interprets the nodes and compares
     the keys.

     AVLNODECOMP is used to compare the keys of two nodes.

     typedef LONG *AVLNODECOMP(const struct AVLNode *avlnode1,
                               const struct AVLNode *avlnode2);
             D0                A0, A1

     AVLKEYCOMP is used to compare a key to a node.

     typedef LONG *AVLKEYCOMP(const struct AVLNode *avlnode,
                              AVLKey key);
             D0               A0, A1

     These functions must return the same sense for the same key values.
     That is,
         <0  if key of avlnode1 <  key of avlnode2
             if key of avlnode  <  key
          0  if key of avlnode1 == key of avlnode2
             if key of avlnode  == key
         >0  if key of avlnode1 >  key of avlnode2
             if key of avlnode  <  key

     Since this function returns the existing node if the keys match,
     this function can be used to efficiently add items to the tree or
     update existing items without requiring additional lookups.



See also
~~~~~~~~

`AVL_FindNode()`_ `AVL_FindNextNodeByKey()`_ `AVL_FindPrevNodeByKey()`_ `AVL_RemNodeByAddress()`_ `AVL_RemNodeByKey()`_ 

----------

AVL_FindFirstNode()
===================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_FindFirstNode(
          const struct AVLNode * Root );

Function
~~~~~~~~
::

     Find the smallest node in an AVL tree.


Inputs
~~~~~~
::

     Root - The root node of the AVL tree.


Result
~~~~~~
::

     NULL if the tree is empty (i.e. Root is NULL), or the node
     which contains the least value in the tree as determined by
     the comparision function used to add the node.


Example
~~~~~~~
::

     See AVL_FindNextNodeByAddress()


Notes
~~~~~
::

     AVL trees are balanced but not minimal.  This operation
     must iterate the full depth of the tree on one side -
     approximately 1.44Log(N).



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_FindNextNodeByAddress()`_ 

----------

AVL_FindLastNode()
==================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_FindLastNode(
          const struct AVLNode * Root );

Function
~~~~~~~~
::

     Find the largest node in an AVL tree.


Inputs
~~~~~~
::

     Root - The root node of the AVL tree.


Result
~~~~~~
::

     NULL if the tree is empty (i.e. Root is NULL), or the node
     which contains the greatest value in the tree as determined by
     the comparision function used to add the node.


Example
~~~~~~~
::

     See AVL_FindPrevNodeByAddress()


Notes
~~~~~
::

     AVL trees are balanced but not minimal.  This operation
     must iterate the full depth of the tree on one side -
     approximately 1.44Log(N).



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_FindPrevNodeByAddress()`_ 

----------

AVL_FindNextNodeByAddress()
===========================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_FindNextNodeByAddress(
          const struct AVLNode * Node );

Function
~~~~~~~~
::

     Perform an in-order traversal to the next node in the tree.


Inputs
~~~~~~
::

     Node - The current node.  The node must be present in the tree.


Result
~~~~~~
::

     The next-greatest node in the tree, or NULL if Node was already
     the highest valued node in the tree.


Example
~~~~~~~
::

     ... in-order traversal of all nodes
     node = (struct ExampleNode *)AVL_FindFirstNode(root);
     while (node) {
         printf(" %s\n", node->key);
         node = (struct ExampleNode *)AVL_FindNextNodeByAddress(node);
     }

     ... in-order traversal of all nodes - with safe deletion
     node = (struct ExampleNode *)AVL_FindFirstNode(root);
     next = (struct ExampleNode *)AVL_FindNextNodeByAddress(node);
     while (node) {
         printf(" %s\n", node->key);

         if (DELETE_NODE(node))
             AVL_RemNodeByAddress(&root, node);

         node = next;
         next = (struct ExampleNode *)AVL_FindNextNodeByAddress(node);
     }


Notes
~~~~~
::

     This implementation uses a parent pointer to avoid needing
     a stack or state to track it's current position in the tree.

     Although this operation is typically O(1), in the worst case it
     iterate the full depth of the tree - approximately 1.44Log(N).



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_RemNodeByAddress()`_ `AVL_FindFirstNode()`_ 

----------

AVL_FindNextNodeByKey()
=======================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_FindNextNodeByKey(
          const struct AVLNode * Root,
          AVLKEYCOMP func );

Function
~~~~~~~~
::

     Find the node matching the key, or if such a node does not exist,
     then the node with the next-highest value.


Inputs
~~~~~~
::

     Root - The root of the AVL tree.

     key  - The key to search.

     func - The AVLKEYCOMP key comparision function for this tree.


Result
~~~~~~
::

     A pointer to the struct AVLNode which matches this key, or
     if that key is not present in the tree, the next highest node.
     Or NULL if key is higher than the key of any node in the tree.


Notes
~~~~~
::

     This is only O(1.44log(n)) in the worst case.



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_FindNextNodeByAddress()`_ `AVL_FindLastNode()`_ 

----------

AVL_FindNode()
==============

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_FindNode(
          const struct AVLNode * Root,
          AVLKEYCOMP func );

Function
~~~~~~~~
::

     Find an entry in the AVL tree by key.


Inputs
~~~~~~
::

     Root - The root of the AVL tree.

     key  - The key to search.

     func - The AVLKEYCOMP key comparision function for this tree.


Result
~~~~~~
::

     A pointer to the node matching key if it exists in the
     tree, or NULL if no such node exists.


Example
~~~~~~~
::

     node = (struct ExampleNode *)AVL_FindNode(root, "aros", ExampleKeyComp);
     if (node)
         printf(" `%s' occurs %d times\n", node->key, node->count);



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_RemNodeByAddress()`_ `AVL_FindNextNodeByAddress()`_ `AVL_FindPrevNodeByAddress()`_ 

----------

AVL_FindPrevNodeByAddress()
===========================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_FindPrevNodeByAddress(
          const struct AVLNode * Node );

Function
~~~~~~~~
::

     Perform an inverse-order traversal to the previous node in the tree.


Inputs
~~~~~~
::

     Node - The current node.  The node must be present in the tree.


Result
~~~~~~
::

     The next-least node in the tree, or NULL if Node was already
     the lowest valued node in the tree.


Example
~~~~~~~
::

     ... inverse-order traversal of all nodes
     node = (struct ExampleNode *)AVL_FindLastNode(root);
     while (node) {
         printf(" %s\n", node->key);
         node = (struct ExampleNode *)AVL_FindPrevNodeByAddress(node);
     }

     ... inverse-order traversal of all nodes - with safe deletion
     node = (struct ExampleNode *)AVL_FindLastNode(root);
     prev = (struct ExampleNode *)AVL_FindPrevNodeByAddress(node);
     while (node) {
         printf(" %s\n", node->key);

         if (DELETE_NODE(node))
             AVL_RemNodeByAddress(&root, node);

         node = prev;
         prev = (struct ExampleNode *)AVL_FindPrevNodeByAddress(node);
     }


Notes
~~~~~
::

     This implementation uses a parent pointer to avoid needing
     a stack or state to track it's current position in the tree.

     Although this operation is typically O(1), in the worst case it
     iterate the full depth of the tree - approximately 1.44Log(N).



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_RemNodeByAddress()`_ `AVL_FindLastNode()`_ 

----------

AVL_FindPrevNodeByKey()
=======================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_FindPrevNodeByKey(
          const struct AVLNode * root,
          AVLKEYCOMP func );

Function
~~~~~~~~
::

     Find the node matching the key, or if such a node does not exist,
     then the node with the next-lowest value.


Inputs
~~~~~~
::

     Root - The root of the AVL tree.

     key  - The key to search.

     func - The AVLKEYCOMP key comparision function for this tree.


Result
~~~~~~
::

     A pointer to the struct AVLNode which matches this key, or
     if that key is not present in the tree, the next lowest node.
     Or NULL if key is lower than the key of any node in the tree.


Notes
~~~~~
::

     This is only O(1.44log(n)) in the worst case.



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_FindNextNodeByAddress()`_ `AVL_FindLastNode()`_ 

----------

AVL_RemNodeByAddress()
======================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_RemNodeByAddress(
          struct AVLNode ** Root,
          struct AVLNode * Node );

Function
~~~~~~~~
::

     Remove a given node from the tree.


Inputs
~~~~~~
::

     Root - A pointer to a pointer to the root node of the tree.

     Node - A struct AVLNode to remove.  The node must be present
            in the tree.


Result
~~~~~~
::

     Node is returned.


Example
~~~~~~~
::

     See AVL_FindNextNodeByAddress(), AVL_FindPrevNodeByAddress()


Notes
~~~~~
::

     Removing a node may require multiple rebalancing steps
     in the tree.  Each step however runs in constant time
     and no more than 1.44log(n) steps will be required.



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_FindNode()`_ `AVL_FindNextNodeByAddress()`_ `AVL_FindPrevNodeByAddress()`_ 

----------

AVL_RemNodeByKey()
==================

Synopsis
~~~~~~~~
::

 struct AVLNode * AVL_RemNodeByKey(
          struct AVLNode ** root,
          AVLKEYCOMP func );

Function
~~~~~~~~
::

     Looks up a node in the tree by key, and removes it if it
     is found.


Inputs
~~~~~~
::

     Root - A pointer to a pointer to the root node of the AVL tree.

     key  - The key to search for.

     func - An AVLKEYCOMP function used to compare the key and nodes
            in the tree.


Result
~~~~~~
::

     If the key was present in the tree, then a pointer to the node
     for that key.  Otherwise NULL if no such key existed in the
     tree.


Notes
~~~~~
::

     See AVL_RemNodeByAddress().



See also
~~~~~~~~

`AVL_AddNode()`_ `AVL_RemNodeByAddress()`_ 

----------

CacheClearE()
=============

Synopsis
~~~~~~~~
::

 void CacheClearE(
          APTR address,
          IPTR length,
          ULONG caches );

Function
~~~~~~~~
::

     Flush the contents of the CPU instruction or data caches. If some
     of the cache contains dirty data, push it to memory first.

     For most systems DMA will not effect processor caches. If *any*
     external (non-processor) event changes system memory, you MUST
     clear the cache. For example:

         DMA
         Code relocation to run at a different address
         Building jump tables
         Loading code from disk


Inputs
~~~~~~
::

     address -   Address to start the operation. This address may be
                 rounded DOWN due to hardware granularity.
     length  -   Length of the memory to flush. This will be rounded
                 up, of $FFFFFFFF to indicate that all addresses
                 should be cleared.
     caches  -   Bit flags to indicate which caches should be cleared

                     CACRF_ClearI    -   Clear the instruction cache
                     CACRF_ClearD    -   Clear the data cache

                 All other bits are reserved.


Result
~~~~~~
::

     The caches will be flushed.


Notes
~~~~~
::

     It is possible that on some systems the entire cache will be
     even if this was not the specific request.



See also
~~~~~~~~

`CacheClearU()`_ `CacheControl()`_ 

----------

CacheClearU()
=============

Synopsis
~~~~~~~~
::

 void CacheClearU();

Function
~~~~~~~~
::

     Flush the entire contents of the CPU instruction and data caches.
     If some of the cache contains dirty data, push it to memory first.

     For most systems DMA will not effect processor caches. If *any*
     external (non-processor) event changes system memory, you MUST
     clear the cache. For example:

         DMA
         Code relocation to run at a different address
         Building jump tables
         Loading code from disk


Result
~~~~~~
::

     The caches will be flushed.


Notes
~~~~~
::

     It is possible that on some systems the entire cache will be
     even if this was not the specific request.



See also
~~~~~~~~

`CacheClearE()`_ `CacheControl()`_ `CachePreDMA()`_ `CachePostDMA()`_ 

----------

CacheControl()
==============

Synopsis
~~~~~~~~
::

 ULONG CacheControl(
          ULONG cacheBits,
          ULONG cacheMask );

Function
~~~~~~~~
::

     This function will provide global control of all the processor
     instruction and data caches. It is not possible to have per
     task control.

     The actions undertaken by this function are very CPU dependant,
     however the actions performed will match the specified options
     as close as is possible.

     The commands currently defined in the include file exec/execbase.h
     are closely related to the cache control register of the Motorola
     MC68030 CPU.


Inputs
~~~~~~
::

     cacheBits   -   The new state of the bits
     cacheMask   -   A mask of the bits you wish to change.


Result
~~~~~~
::

     oldBits     -   The complete value of the cache control bits
                     prior to the call of this function.

     Your requested actions will have been performed. As a side effect
     this function will also cause the caches to be cleared.


Notes
~~~~~
::

     On CPU's without a separate instruction and data cache, these will
     be considered as equal.

     This function isn't implemented on all platforms.



See also
~~~~~~~~

`CacheClearE()`_ `CacheClearU()`_ 

----------

CachePostDMA()
==============

Synopsis
~~~~~~~~
::

 void CachePostDMA(
          APTR address,
          ULONG * length,
          ULONG flags );
 
 void CachePostDM(
          APTR address,
          ULONG * length,
          TAG tag, ... );

Function
~~~~~~~~
::

     Do everything necessary to make CPU caches aware that a DMA has
     happened.


Inputs
~~~~~~
::

     address - Virtual address of memory affected by the DMA
     *length - Number of bytes affected
     flags   - DMA_NoModify    - Indicate that the memory did not change.
               DMA_ReadFromRAM - Indicate that the DMA goes from RAM
                                 to the device. Set this bit in
                                 both calls.


Notes
~~~~~
::

     DMA must follow a call to CachePreDMA() and must be followed
     by a call to CachePostDMA().



See also
~~~~~~~~

`CachePreDMA()`_ 

----------

CachePreDMA()
=============

Synopsis
~~~~~~~~
::

 APTR CachePreDMA(
          APTR address,
          ULONG * length,
          ULONG flags );
 
 APTR CachePreDM(
          APTR address,
          ULONG * length,
          TAG tag, ... );

Function
~~~~~~~~
::

     Do everything necessary to make CPU caches aware that a DMA
     will happen. Virtual memory systems will make it possible
     that your memory is not at one block and not at the address
     you thought. This function gives you all the information
     you need to split the DMA request up and to convert virtual
     to physical addresses.


Inputs
~~~~~~
::

     address - Virtual address of memory affected by the DMA
     *length - Number of bytes affected
     flags   - DMA_Continue    - This is a call to continue a
                                 request that was broken up.
               DMA_ReadFromRAM - Indicate that the DMA goes from
                                 RAM to the device. Set this bit
                                 in both calls.


Result
~~~~~~
::

     The physical address in memory.
     *length contains the number of contiguous bytes in physical
     memory.


Notes
~~~~~
::

     DMA must follow a call to CachePreDMA() and must be followed
     by a call to CachePostDMA().



See also
~~~~~~~~

`CachePostDMA()`_ 

----------

Cause()
=======

Synopsis
~~~~~~~~
::

 void Cause(
          struct Interrupt * softint );

Function
~~~~~~~~
::

     Schedule a software interrupt to occur. If the processor is
     currently running a user task, then the software interrupt will
     pre-empt the current task and run itself. From a real interrupt, it
     will queue the software interrupt for a later time.

     Software interrupts are useful from hardware interrupts if you
     wish to defer your processing down to a lower level. They can
     also be used in some special cases of device I/O. The timer.device
     and audio.device allow software interrupt driven timing and
     audio output respectively.

     Software interrupts are restricted to 5 different priority levels,
     +32, +16, 0, -16, -32.

     Software interrupts can only be scheduled once.

     The software interrupt is called with the following prototype:

 AROS_INTC1(YourIntCode, APTR, interruptData)

     The interruptData is the value of the is_Data field.


Inputs
~~~~~~
::

     softint     -   The interrupt you wish to schedule. When setting up
                     you should set the type of the interrupt to either
                     NT_INTERRUPT or NT_UNKNOWN.


Result
~~~~~~
::

     The software interrupt will be delivered, or queued for later
     delivery.


Notes
~~~~~
::

     No bounds checking on the software interrupt priority is done.
     Passing a bad priority to the system can have a strange effect.


Bugs
~~~~
::

     Older versions of the Amiga operating system require that the
     software interrupts preserve the A6 register.

     Software interrupts which are added from a software interrupt of
     lower priority may not be called immediately.



----------

CheckIO()
=========

Synopsis
~~~~~~~~
::

 struct IORequest * CheckIO(
          struct IORequest * iORequest );

Function
~~~~~~~~
::

     Check if an I/O request is completed.


Inputs
~~~~~~
::

     iORequest - Pointer to iorequest structure.


Result
~~~~~~
::

     Pointer to the iorequest structure or NULL if the device is still
     at work.



See also
~~~~~~~~

`OpenDevice()`_ `CloseDevice()`_ `DoIO()`_ `SendIO()`_ `AbortIO()`_ `WaitIO()`_ 

----------

ChildFree()
===========

Synopsis
~~~~~~~~
::

 void ChildFree(
          ULONG tid );

Function
~~~~~~~~
::

     Clean up after a child process.


Inputs
~~~~~~
::

     tid     --  Id of the child to clean up. This is not the same as
                 the Task pointer.


Result
~~~~~~
::

     The child will be freed.


Notes
~~~~~
::

     This function will work correctly only for child tasks that are
     processes created with NP_NotifyOnDeath set to TRUE.

     Calling ChildFree() on a running child is likely to crash your
     system badly.



----------

ChildOrphan()
=============

Synopsis
~~~~~~~~
::

 ULONG ChildOrphan(
          ULONG tid );

Function
~~~~~~~~
::

     ChildOrphan() will detach the specified task from its parent
     task's child task tree. This is useful if the parent task will be
     exiting, and no longer needs to be told about child task events.

     Note that the default Task finaliser will orphan any remaining
     children when the task exits. This function can be used if you just
     do not wish to be told about a particular task.


Inputs
~~~~~~
::

     tid     --  The ID of the task to orphan, or 0 for all tasks. Note
                 that it is NOT the pointer to the task.


Result
~~~~~~
::

     Will return 0 on success or CHILD_* on an error.

     The child/children will no longer participate in child task
     actions.



----------

ChildStatus()
=============

Synopsis
~~~~~~~~
::

 ULONG ChildStatus(
          ULONG tid );

Function
~~~~~~~~
::

     Return the status of a child task. This allows the Task to
     determine whether a particular child task is still running or not.


Inputs
~~~~~~
::

     tid     --  The ID of the task to examine. Note that it is _NOT_
                 a task pointer.


Result
~~~~~~
::

     One of the CHILD_* values.


Notes
~~~~~
::

     This function will work correctly only for child tasks that are
     processes created with NP_NotifyOnDeath set to TRUE. Otherwise
     it may report CHILD_NOTFOUND even if child already exited.



----------

ChildWait()
===========

Synopsis
~~~~~~~~
::

 IPTR ChildWait(
          ULONG tid );

Function
~~~~~~~~
::

     Wait for either a specific child task, or any child task to finish.
     If you specify tid = 0, then the call will return when any child
     task exits, otherwise it will not return until the requested task
     finishes.

     Note that the tid is NOT the task control block (ie struct Task *),
     rather it is the value of the ETask et_UniqueID field. Passing in a
     Task pointer will cause your Task to deadlock.

     You must call ChildFree() on the returned task before calling
     ChildWait() again. Ie.

         struct ETask *et;

         et = ChildWait(0);
         ChildFree(et->et_UniqueID);


Inputs
~~~~~~
::

     tid -   The UniqueID of a task.


Result
~~~~~~
::

     Returns either the ETask structure of the child, or one of the
     CHILD_* values on error.

     This allows you to work out which of the children has exited.


Notes
~~~~~
::

     This function will work correctly only for child tasks that are
     processes created with NP_NotifyOnDeath set to TRUE.

     Calling ChildWait() on a task that isn't your child will result in
     a deadlock.


Bugs
~~~~
::

     Be careful with the return result of this function.



----------

CloseDevice()
=============

Synopsis
~~~~~~~~
::

 void CloseDevice(
          struct IORequest * iORequest );

Function
~~~~~~~~
::

     Closes a previously opened device. Any outstanding I/O requests must
     be finished. It is safe to call CloseDevice with a cleared iorequest
     structure or one that failed to open.


Inputs
~~~~~~
::

     iORequest - Pointer to iorequest structure.



See also
~~~~~~~~

`OpenDevice()`_ 

----------

CloseLibrary()
==============

Synopsis
~~~~~~~~
::

 void CloseLibrary(
          struct Library * library );

Function
~~~~~~~~
::

     Closes a previously opened library. It is legal to call this function
     with a NULL pointer.


Inputs
~~~~~~
::

     library - Pointer to library structure or NULL.



See also
~~~~~~~~

`OpenLibrary()`_ 

----------

ColdReboot()
============

Synopsis
~~~~~~~~
::

 void ColdReboot();

Function
~~~~~~~~
::

     This function will reboot the computer.


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     This function does not return.


Notes
~~~~~
::

     It can be quite harmful to call this function. It may be possible that
     you will lose data from other tasks not having saved, or disk buffers
     not being flushed. Plus you could annoy the (other) users.



----------

CopyMem()
=========

Synopsis
~~~~~~~~
::

 void CopyMem(
          CONST_APTR source,
          APTR dest,
          IPTR size );

Function
~~~~~~~~
::

     Copy some memory from one destination in memory to another using
     a fast copying method.


Inputs
~~~~~~
::

     source - Pointer to source area
     dest   - Pointer to destination
     size   - number of bytes to copy (may be zero)


Notes
~~~~~
::

     The source and destination area are not allowed to overlap.



See also
~~~~~~~~

`CopyMemQuick()`_ 

----------

CopyMemQuick()
==============

Synopsis
~~~~~~~~
::

 void CopyMemQuick(
          CONST_APTR source,
          APTR dest,
          IPTR size );

Function
~~~~~~~~
::

     Copy some longwords from one destination in memory to another using
     a fast copying method.


Inputs
~~~~~~
::

     source - Pointer to source area (must be ULONG aligned)
     dest   - Pointer to destination (must be ULONG aligned)
     size   - number of bytes to copy (must be a multiple of sizeof(ULONG)).
              May be zero.


Notes
~~~~~
::

     The source and destination areas are not allowed to overlap.



See also
~~~~~~~~

`CopyMem()`_ 

----------

CreateIORequest()
=================

Synopsis
~~~~~~~~
::

 APTR CreateIORequest(
          struct MsgPort * ioReplyPort,
          ULONG size );

Function
~~~~~~~~
::

     Create an I/O request structure bound to a given messageport.
     I/O requests are normally used to communicate with exec devices
     but can be used as normal messages just as well.


Inputs
~~~~~~
::

     ioReplyPort - Pointer to that one of your messageports where
                   the messages are replied to. A NULL port is legal
                   but then the function fails always.
     size        - Size of the message structure including the struct
                   IORequest header. The minimal allowable size is that
                   of a struct Message.


Result
~~~~~~
::

     Pointer to a new I/O request structure or NULL if the function
     failed.



----------

CreateMsgPort()
===============

Synopsis
~~~~~~~~
::

 struct MsgPort * CreateMsgPort();

Function
~~~~~~~~
::

     Create a new message port. A signal will be allocated and the message
     port set to signal you task


Result
~~~~~~
::

     Pointer to messageport structure



----------

CreatePool()
============

Synopsis
~~~~~~~~
::

 APTR CreatePool(
          ULONG requirements,
          IPTR puddleSize,
          IPTR threshSize );

Function
~~~~~~~~
::

     Create a private pool for memory allocations.


Inputs
~~~~~~
::

     requirements - The type of the memory
     puddleSize   - The number of bytes that the pool expands by
                if it is too small.
     threshSize   - Allocations beyond the threshSize are given
                directly to the system. threshSize must be
                smaller than or equal to the puddleSize.


Result
~~~~~~
::

     A handle for the memory pool or NULL if the pool couldn't
     be created


Example
~~~~~~~
::

     \* Get the handle to a private memory pool *\
     po=CreatePool(MEMF_ANY,16384,8192);
     if(po!=NULL)
     {
         \* Use the pool *\
         UBYTE *mem1,*mem2;
         mem1=AllocPooled(po,1000);
         mem2=AllocPooled(po,2000);
         \* Do something with the memory... *\

         \* Free everything at once *\
         DeletePool(po);
     }


Notes
~~~~~
::

     Since exec.library v41.12, the implementation of pools has been
     rewritten to make use of memory protection capabilities. The
     threshSize parameter is effectively ignored and is present only
     for backwards compatibility.



See also
~~~~~~~~

`DeletePool()`_ `AllocPooled()`_ `FreePooled()`_ 

----------

Deallocate()
============

Synopsis
~~~~~~~~
::

 void Deallocate(
          struct MemHeader * freeList,
          APTR memoryBlock,
          IPTR byteSize );

Function
~~~~~~~~
::

     Free block of memory associated with a given MemHandler structure.


Inputs
~~~~~~
::

     freeList    - Pointer to the MemHeader structure
     memoryBlock - Pointer to the memory to be freed
     byteSize    - Size of the block


Notes
~~~~~
::

     The start and end borders of the block are aligned to
     a multiple of sizeof(struct MemChunk) and to include the block.



See also
~~~~~~~~

`Allocate()`_ 

----------

Debug()
=======

Synopsis
~~~~~~~~
::

 void Debug(
          ULONG flags );

Function
~~~~~~~~
::

     Runs SAD - internal debuger.


Inputs
~~~~~~
::

     flags   not used. Should be 0 now.



----------

DeleteIORequest()
=================

Synopsis
~~~~~~~~
::

 void DeleteIORequest(
          APTR iorequest );

Function
~~~~~~~~
::

     Delete an I/O request created with CreateIORequest().


Inputs
~~~~~~
::

     iorequest - Pointer to I/O request structure or NULL.



----------

DeleteMsgPort()
===============

Synopsis
~~~~~~~~
::

 void DeleteMsgPort(
          struct MsgPort * port );

Function
~~~~~~~~
::

     Delete a messageport allocated with CreateMsgPort(). The signal bit
     is freed and the memory is given back to the memory pool. Remaining
     messages are not replied. It is safe to call this function with a
     NULL pointer.


Inputs
~~~~~~
::

     port - Pointer to messageport structure.



----------

DeletePool()
============

Synopsis
~~~~~~~~
::

 void DeletePool(
          APTR poolHeader );

Function
~~~~~~~~
::

     Delete a pool including all its memory.


Inputs
~~~~~~
::

     poolHeader - The pool allocated with CreatePool() or NULL.



See also
~~~~~~~~

`CreatePool()`_ `AllocPooled()`_ `FreePooled()`_ `AllocVecPooled()`_ `FreeVecPooled()`_ 

----------

Disable()
=========

Synopsis
~~~~~~~~
::

 void Disable();

Function
~~~~~~~~
::

     This function will prevent interrupts from occuring. You can
     start the interrupts again with a call to Enable().

     Note that calls to Disable() nest, and for every call to
     Disable() you need a matching call to Enable().

     ***** WARNING *****

     Using this function is considered very harmful, and it should only
     ever be used to protect data that could also be accessed in interrupts.

     It is quite possible to either crash the system, or to prevent
     normal activities (disk/port i/o) from occuring.


Result
~~~~~~
::

     Interrupts will be disabled AFTER this call returns.


Example
~~~~~~~
::

     In most userspace code, you will not want to use this function.


Notes
~~~~~
::

     This function preserves all registers.

     To prevent deadlocks calling Wait() in disabled state breaks
     the disable - thus interrupts may happen again.

     As the schedulers pre-emption is interrupt driven,
     this function has the side effect of disabling
     multitasking.


Bugs
~~~~
::

     The only architecture that you can rely on the registers being
     saved is on the Motorola mc68000 family.



See also
~~~~~~~~

`Forbid()`_ `Permit()`_ `Enable()`_ `Wait()`_ 

----------

Dispatch()
==========

Synopsis
~~~~~~~~
::

 void Dispatch();

Function
~~~~~~~~
::

     PRIVATE function to dispatch next available task


Inputs
~~~~~~
::

     None


Result
~~~~~~
::

     None


Notes
~~~~~
::

     This function was private in AmigaOS(tm) up to v3.1.
     There's no guarantee that it will continue to exist in other systems.



----------

DoIO()
======

Synopsis
~~~~~~~~
::

 LONG DoIO(
          struct IORequest * iORequest );

Function
~~~~~~~~
::

     Start an I/O request by calling the devices's BeginIO() vector.
     It waits until the request is complete.


Inputs
~~~~~~
::

     iORequest - Pointer to iorequest structure.


Notes
~~~~~
::

     OpenDevice() notes explain LONG return type.



See also
~~~~~~~~

`OpenDevice()`_ `CloseDevice()`_ `DoIO()`_ `SendIO()`_ `AbortIO()`_ `WaitIO()`_ 

----------

Enable()
========

Synopsis
~~~~~~~~
::

 void Enable();

Function
~~~~~~~~
::

     This function will allow interrupts to occur after they have
     been disabled by Disable().

     Note that calls to Disable() nest, and for every call to
     Disable() you need a matching call to Enable().

     ***** WARNING *****


     Using this function is considered very harmful, and it should only
     ever be used to protect data that could also be accessed in interrupts.

     It is quite possible to either crash the system, or to prevent
     normal activities (disk/port i/o) from occuring.


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     Interrupts will be enabled again when this call returns.


Example
~~~~~~~
::

     In most userspace code, you will not want to use this function.


Notes
~~~~~
::

     This function preserves all registers.

     To prevent deadlocks calling Wait() in disabled state breaks
     the disable - thus interrupts may happen again.

     As the schedulers pre-emption is interrupt driven,
     this function has the side effect of disabling
     multitasking.


Bugs
~~~~
::

     The only architecture that you can rely on the registers being
     saved is on the Motorola mc68000 family.



See also
~~~~~~~~

`Forbid()`_ `Permit()`_ `Disable()`_ `Wait()`_ 

----------

Enqueue()
=========

Synopsis
~~~~~~~~
::

 void Enqueue(
          struct List * list,
          struct Node * node );

Function
~~~~~~~~
::

     Sort a node into a list. The sort-key is the field node->ln_Pri.
     The node will be inserted into the list before the first node
     with lower priority. This creates a FIFO queue for nodes with
     the same priority.


Inputs
~~~~~~
::

     list - Insert into this list. The list has to be in descending
             order in respect to the field ln_Pri of all nodes.
     node - This node is to be inserted. Note that this has to
             be a complete node and not a MinNode !


Result
~~~~~~
::

     The new node will be inserted before nodes with lower
     priority.


Example
~~~~~~~
::

     struct List * list;
     struct Node * node;

     node->ln_Pri = 5;

     // Sort the node at the correct place into the list
     Enqueue (list, node);


Notes
~~~~~
::

     The list has to be in descending order in respect to the field
     ln_Pri of all nodes.



----------

Exec_FindChild()
================

Synopsis
~~~~~~~~
::

  struct ETask * Exec_FindChild(
     ULONG       id,
     struct ExecBase *SysBase)


Function
~~~~~~~~
::

     Scan through the current tasks children list searching for the task
     whose et_UniqueID field matches.


Inputs
~~~~~~
::

     id      -   The task ID to match.


Result
~~~~~~
::

     Address of the ETask structure that matches, or
     NULL otherwise.


Notes
~~~~~
::

     This is an internal exec.library function not exported from the
     library.



----------

ExitIntr()
==========

Synopsis
~~~~~~~~
::

 void ExitIntr();

Function
~~~~~~~~
::

     PRIVATE architecture specific routine for exiting interrupts.


Inputs
~~~~~~
::

     None


Result
~~~~~~
::

     None


Notes
~~~~~
::

     This function was private in AmigaOS(tm) up to v3.1.
     There's no guarantee that it will exist in other systems.



----------

FindName()
==========

Synopsis
~~~~~~~~
::

 struct Node * FindName(
          struct List * list,
          CONST_STRPTR name );

Function
~~~~~~~~
::

     Look for a node with a certain name in a list.


Inputs
~~~~~~
::

     list - Search this list.
     name - This is the name to look for.


Example
~~~~~~~
::

     struct List * list;
     struct Node * node;

     // Look for a node with the name "Hello"
     node = FindName (list, "Hello");


Notes
~~~~~
::

     The search is case-sensitive, so "Hello" will not find a node
     named "hello".

     The list must contain complete Nodes and no MinNodes.

     When supplied with a NULL list argument, defaults to the exec port list.



----------

FindPort()
==========

Synopsis
~~~~~~~~
::

 struct MsgPort * FindPort(
          CONST_STRPTR name );

Function
~~~~~~~~
::

     Look for a public messageport by name. This function doesn't
     arbitrate for the port list and must be protected with a Forbid()
     Permit() pair.


Inputs
~~~~~~
::

     port - Pointer to NUL terminated C string.


Result
~~~~~~
::

     Pointer to struct MsgPort or NULL if there is no port of that name.



----------

FindResident()
==============

Synopsis
~~~~~~~~
::

 struct Resident * FindResident(
          const UBYTE * name );

Function
~~~~~~~~
::

     Search for a Resident module in the system resident list.


Inputs
~~~~~~
::

     name - pointer to the name of a Resident module to find


Result
~~~~~~
::

     pointer to the Resident module (struct Resident *), or null if
     not found.



----------

FindSemaphore()
===============

Synopsis
~~~~~~~~
::

 struct SignalSemaphore * FindSemaphore(
          CONST_STRPTR name );

Function
~~~~~~~~
::

     Find a semaphore with a given name in the system global semaphore list.
     Note that this call doesn't arbitrate for the list - use Forbid() to
     do this yourself.


Inputs
~~~~~~
::

     name - Pointer to name.


Result
~~~~~~
::

     Address of semaphore structure found or NULL.



----------

FindTask()
==========

Synopsis
~~~~~~~~
::

 struct Task * FindTask(
          CONST_STRPTR name );

Function
~~~~~~~~
::

     Find a task with a given name or get the address of the current task.
     Finding the address of the current task is a very quick function
     call, but finding a special task is a very CPU intensive instruction.
     Note that generally a task may already be gone when this function
     returns.


Inputs
~~~~~~
::

     name - Pointer to name or NULL for current task.


Result
~~~~~~
::

     Address of task structure found.



----------

FindTaskByPID()
===============

Synopsis
~~~~~~~~
::

 struct Task * FindTaskByPID(
          ULONG id );

Function
~~~~~~~~
::

     Scan through the task lists searching for the task whose
     et_UniqueID field matches.


Inputs
~~~~~~
::

     id      -   The task ID to match.


Result
~~~~~~
::

     Address of the Task control structure that matches, or
     NULL otherwise.


Notes
~~~~~
::

     This function is source-compatible with MorphOS.



----------

Forbid()
========

Synopsis
~~~~~~~~
::

 void Forbid();

Function
~~~~~~~~
::

     Forbid any further taskswitches until a matching call to Permit().
     Naturally disabling taskswitches means:

     THIS CALL IS DANGEROUS

     Do not use it without thinking very well about it or better
     do not use it at all. Most of the time you can live without
     it by using semaphores or similar.

     Calls to Forbid() nest, i.e. for each call to Forbid() you
     need one call to Permit().


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     The multitasking state will be disabled AFTER this function
     returns to the caller.


Example
~~~~~~~
::

     It is generally not necessary/desirable to use Forbid()/Permit()
     in most userspace code.


Notes
~~~~~
::

     This function preserves all registers.

     To prevent deadlocks calling Wait() in forbidden state breaks
     the forbid - thus taskswitches may happen again.


Bugs
~~~~
::

     The only architecture that you can rely on the registers being
     saved is on the Motorola mc68000 family.



See also
~~~~~~~~

`Permit()`_ `Disable()`_ `Enable()`_ `Wait()`_ 

----------

FreeEntry()
===========

Synopsis
~~~~~~~~
::

 void FreeEntry(
          struct MemList * entry );

Function
~~~~~~~~
::

     Free some memory allocated with AllocEntry().


Inputs
~~~~~~
::

     entry - The MemList you got from AllocEntry().



See also
~~~~~~~~

`AllocEntry()`_ 

----------

FreeMem()
=========

Synopsis
~~~~~~~~
::

 void FreeMem(
          APTR memoryBlock,
          IPTR byteSize );

Function
~~~~~~~~
::

     Give a block of memory back to the system pool.


Inputs
~~~~~~
::

     memoryBlock - Pointer to the memory to be freed
     byteSize    - Size of the block



See also
~~~~~~~~

`AllocMem()`_ 

----------

FreePooled()
============

Synopsis
~~~~~~~~
::

 void FreePooled(
          APTR poolHeader,
          APTR memory,
          IPTR memSize );

Function
~~~~~~~~
::

     Free memory that was allocated out of a private memory pool by
     AllocPooled().


Inputs
~~~~~~
::

     poolHeader - Handle of the memory pool
     memory       - Pointer to the memory
     memSize    - Size of the memory chunk



See also
~~~~~~~~

`CreatePool()`_ `DeletePool()`_ `AllocPooled()`_ 

----------

FreeSignal()
============

Synopsis
~~~~~~~~
::

 void FreeSignal(
          LONG signalNum );

Function
~~~~~~~~
::

     Free a signal allocated with AllocSignal().


Inputs
~~~~~~
::

     signalNum - Number of the signal to free or -1 to do nothing.



See also
~~~~~~~~

`AllocSignal()`_ `Signal()`_ `Wait()`_ 

----------

FreeTaskStorageSlot()
=====================

Synopsis
~~~~~~~~
::

 void FreeTaskStorageSlot();

Function
~~~~~~~~
::

     This function will free a slot in taskstorage


Inputs
~~~~~~
::

     slot - The slot to free.


Result
~~~~~~
::

     None.


Notes
~~~~~
::

     Currently no checks are performed to determine if one is the owner
     of the slot. This may be added in the future, so one should
     deallocate a slot from the same task that allocated the slot.



See also
~~~~~~~~

`AllocTaskStorageSlot()`_ 

----------

FreeTrap()
==========

Synopsis
~~~~~~~~
::

 void FreeTrap(
          long trapNum );


----------

FreeVec()
=========

Synopsis
~~~~~~~~
::

 void FreeVec(
          APTR memoryBlock );

Function
~~~~~~~~
::

     Free some memory previously allocated with AllocVec().


Inputs
~~~~~~
::

     memoryBlock - The memory to be freed. It is safe to try to free a NULL
                   pointer.



See also
~~~~~~~~

`AllocVec()`_ 

----------

FreeVecPooled()
===============

Synopsis
~~~~~~~~
::

 void FreeVecPooled(
          APTR poolHeader,
          APTR memory );

Function
~~~~~~~~
::

     Free memory that was allocated out of a private memory pool by
     AllocVecPooled().


Inputs
~~~~~~
::

     poolHeader - Handle of the memory pool
     memory     - Pointer to the memory



See also
~~~~~~~~

`CreatePool()`_ `DeletePool()`_ `AllocVecPooled()`_ 

----------

GetCC()
=======

Synopsis
~~~~~~~~
::

 UWORD GetCC();

Function
~~~~~~~~
::

     Read the contents of the CPU condition code register in a system
     independant way. The flags return will be in the same format as
     the Motorola MC680x0 family of microprocessors.


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     The CPU condition codes or ~0ul if this function has not been
     implemented.


Bugs
~~~~
::

     This function may not be implemented on platforms other than
     Motorola mc680x0 processors.



See also
~~~~~~~~

`SetSR()`_ 

----------

GetMsg()
========

Synopsis
~~~~~~~~
::

 struct Message * GetMsg(
          struct MsgPort * port );

Function
~~~~~~~~
::

     Get a message from a given messageport. This function doesn't wait
     and returns NULL if the messageport is empty. Therefore it's
     generally a good idea to WaitPort() or Wait() on the given port first.


Inputs
~~~~~~
::

     port - Pointer to messageport


Result
~~~~~~
::

     Pointer to message removed from the port.



See also
~~~~~~~~

`WaitPort()`_ `PutMsg()`_ 

----------

GetParentTaskStorageSlot()
==========================

Synopsis
~~~~~~~~
::

 IPTR GetParentTaskStorageSlot();

Function
~~~~~~~~
::

     Get a value for a task storage slot of parent task.


Inputs
~~~~~~
::

     id - slot ID returned from AllocTaskStorageSlot().


Result
~~~~~~
::

     Value stored by SetTaskStorageSlot() on parent task, or
     (IPTR)NULL if the slot was never used.


Notes
~~~~~
::

     Since you are accessing value of another task, the value
     might be invalid/freed by the time this function returns.
     To be sure value is still valid, call this function under
     Forbid().



See also
~~~~~~~~

`AllocTaskStorageSlot()`_ `FreeTaskStorageSlot()`_ `SetTaskStorageSlot()`_ `GetTaskStorageSlot()`_ 

----------

GetTaskStorageSlot()
====================

Synopsis
~~~~~~~~
::

 IPTR GetTaskStorageSlot();

Function
~~~~~~~~
::

     Get a value for a task storage slot.


Inputs
~~~~~~
::

     id - slot ID returned from AllocTaskStorageSlot().


Result
~~~~~~
::

     Value stored by SetTaskStorageSlot(), or (IPTR)NULL if the slot was
     never used.



See also
~~~~~~~~

`AllocTaskStorageSlot()`_ `FreeTaskStorageSlot()`_ `SetTaskStorageSlot()`_ 

----------

InitCode()
==========

Synopsis
~~~~~~~~
::

 void InitCode(
          ULONG startClass,
          ULONG version );

Function
~~~~~~~~
::

     Traverse the ResModules array and InitResident() all modules with
     versions greater than or equal to version, and of a class equal to
     startClass.


Inputs
~~~~~~
::

     startClass - which type of module to start
     version - a version number


Notes
~~~~~
::

     This is actually internal function. There's no sense to call it from
     within user software.



----------

InitResident()
==============

Synopsis
~~~~~~~~
::

 APTR InitResident(
          struct Resident * resident,
          BPTR segList );

Function
~~~~~~~~
::

     Test the resident structure and build the library or device
     with the information given therein. The Init() vector is
     called and the base address returned.

     The Init() vector is called with the following registers:
             D0 = 0
             A0 = segList
             A6 = ExecBase


Inputs
~~~~~~
::

     resident - Pointer to resident structure.
     segList  - Pointer to loaded module, 0 for resident modules.


Result
~~~~~~
::

     A pointer returned from the Init() vector. Usually this is the
     base of the library/device/resource. NULL for failure.


Notes
~~~~~
::

     AUTOINIT modules are automatically added to the correct exec list.
     Non AUTOINIT modules have to do all the work themselves.



----------

InitSemaphore()
===============

Synopsis
~~~~~~~~
::

 void InitSemaphore(
          struct SignalSemaphore * sigSem );

Function
~~~~~~~~
::

     Prepares a semaphore structure for use by the exec semaphore system,
     i.e. this function must be called after allocating the semaphore and
     before using it or the semaphore functions will fail.


Inputs
~~~~~~
::

     sigSem - Pointer to semaphore structure


Notes
~~~~~
::

     Semaphores are shared between the tasks that use them and must
     therefore lie in public (or at least shared) memory.



----------

InitStruct()
============

Synopsis
~~~~~~~~
::

 void InitStruct(
          CONST_APTR initTable,
          APTR memory,
          ULONG size );

Function
~~~~~~~~
::

     Initialize some library base or other structure depending on the
     information in the init table. The init table consists of
     instructions starting with an action byte followed by more
     information. The instruction byte looks like:

     iisscccc where ii is the instruction code:
                       0 - copy following c+1 elements
                       1 - repeat following element c+1 times
                       2 - take next byte as offset, then copy
                       3 - take the next 3 bytes (in the machine's
                           particular byte ordering) as offset, then
                           copy
                    ss is the element size
                       0 - LONGs
                       1 - WORDs
                       2 - BYTEs
                       3 - QUADs
                    cccc is the element count-1

     Instruction bytes must follow the same alignment restrictions as LONGs;
     the following elements are aligned to their particular restrictions.

     A 0 instruction ends the init table.


Inputs
~~~~~~
::

     initTable - Pointer to init table.
     memory    - Pointer to uninitialized structure.
     size      - Size of memory area to zero out before decoding or 0
                 for no filling.



----------

Insert()
========

Synopsis
~~~~~~~~
::

 void Insert(
          struct List * list,
          struct Node * node,
          struct Node * pred );

Function
~~~~~~~~
::

     Insert Node node after pred in list.


Inputs
~~~~~~
::

     list - The list to insert the node into
     node - This node is to be inserted
     pred - Insert after this node. If this is NULL, node is inserted
             as the first node (same as AddHead()).


Example
~~~~~~~
::

     struct List * list;
     struct Node * pred, * node;

     // Insert Node node as second node in list
     pred = GetHead (list);
     Insert (list, node, pred);



See also
~~~~~~~~

`AddHead()`_ `AddTail()`_ `Enqueue()`_ `RemHead()`_ `Remove()`_ `RemTail()`_ "AROS: Exec Lists". 

----------

MakeFunctions()
===============

Synopsis
~~~~~~~~
::

 ULONG MakeFunctions(
          APTR target,
          CONST_APTR functionArray,
          CONST_APTR funcDispBase );

Function
~~~~~~~~
::

     Creates the jumptable for a shared library and flushes the processor's
     instruction cache. Does not checksum the library.


Inputs
~~~~~~
::

     target        - The highest byte +1 of the jumptable. Typically
                     this is the library's base address.
     functionArray - Pointer to either an array of function pointers or
                     an array of WORD displacements to a given location
                     in memory. A value of -1 terminates the array in both
                     cases.
     funcDispBase  - The base location for WORD displacements or NULL
                     for function pointers.


Result
~~~~~~
::

     Size of the jumptable.



----------

MakeLibrary()
=============

Synopsis
~~~~~~~~
::

 struct Library * MakeLibrary(
          CONST_APTR funcInit,
          CONST_APTR structInit,
          ULONG_FUNC libInit,
          ULONG dataSize,
          BPTR segList );

Function
~~~~~~~~
::

     Allocates memory for the library, builds it and calls the library's
     init vector. Generally this function is for internal use and for
     use by library programmers that don't want to use the automatic
     initialization procedure.


Inputs
~~~~~~
::

     funcInit   - Either a pointer to an array of function offsets
                  (starts with -1, relative to funcInit) or to an array
                  of absolute function pointers.
     structInit - Pointer to a InitStruct() data region or NULL.
     libInit    - The library's init vector or NULL.
                  The init vector is called with the library address (D0),
                  the segList (A0) and ExecBase (A6) as arguments.
                  If the init fails the init code has to free the base memory
                  and return NULL (the library address for success).
     dataSize   - Size of the library structure including system structures.
                  Must be at least sizeof(struct Library).
     segList    - BCPL pointer to the library segments. Used to free the
                  library later.


Result
~~~~~~
::

     The library base address or NULL.


Notes
~~~~~
::

     The library base is always aligned to the maximum of sizeof(LONG)
     and double alignment restrictions.



See also
~~~~~~~~

`AddLibrary()`_ `RemLibrary()`_ `MakeFunctions()`_ `InitStruct()`_ `SumLibrary()`_ 

----------

NewAddTask()
============

Synopsis
~~~~~~~~
::

 APTR NewAddTask(
          struct Task * task,
          APTR initialPC,
          APTR finalPC,
          struct TagItem * tagList );
 
 APTR NewAddTaskTags(
          struct Task * task,
          APTR initialPC,
          APTR finalPC,
          TAG tag, ... );

Function
~~~~~~~~
::

     Add a new task to the system. If the new task has the highest
     priority of all and task switches are allowed it will be started
     immediately.
     Certain task fields should be intitialized and a stack must be
     allocated before calling this function. tc_SPReg will be used as the
     starting location for the stack pointer, i.e. a part of the stack can
     be reserved to pass the task some initial arguments.
     Memory can be added to the tc_MemEntry list and will be freed when the
     task dies. The new task's registers are set to 0.


Inputs
~~~~~~
::

     task      - Pointer to task structure.
     initialPC - Entry point for the new task.
     finalPC   - Routine that is called if the initialPC() function returns.
                 A NULL pointer installs the default finalizer.


Result
~~~~~~
::

     The address of the new task or NULL if the operation failed (can only
     happen with TF_ETASK set - currenty not implemented).


Notes
~~~~~
::

     This function is private. Use MorphOS-compatible NewCreateTaskA()
     in your applications.



See also
~~~~~~~~

`RemTask()`_ 

----------

NewAllocEntry()
===============

Synopsis
~~~~~~~~
::

 struct MemList * NewAllocEntry(
          struct MemList * entry,
          ULONG * return_flags );

Function
~~~~~~~~
::

     Allocate a number of memory blocks through a MemList structure.


Inputs
~~~~~~
::

     entry        - The MemList with one MemEntry for each block you want to get
     return_entry - Pointer to struct MemList *variable where the address
                    of the MemList allocated by this function will be stored.
     return_flags - Pointer to ULONG variable where upon failure the type of
                    memory that could not be allocated is stored. You may pass
                    NULL here.


Result
~~~~~~
::

     Address of the allocated MemList if the allocation was successful. In this
     case *return_flags will be set to 0.

     NULL if the allocation failed. In this case *return_flags will contain the
     type of memory that couldn't be allocated.


Notes
~~~~~
::

     This function is AROS-specific.



See also
~~~~~~~~

`AllocEntry()`_ `FreeEntry()`_ 

----------

NewCreateTaskA()
================

Synopsis
~~~~~~~~
::

 struct Task * NewCreateTaskA(
          struct TagItem * tags );
 
 struct Task * NewCreateTask(
          TAG tag, ... );

Function
~~~~~~~~
::

     Create a new task.


Inputs
~~~~~~
::

     tags - TagList which may contain the following tags:

       TASKTAG_ERROR        (ULONG *) - a pointer to an optional location for secondary
                                        return code. The code itself will be set to
                                        TASKERROR_OK on success or TASKERROR_NOMEMORY on
                                        failure.
       TASKTAG_PC           (APTR)    - Start address of the task's code.
       TAGKTAG_FINALPC      (APTR)    - Address of the finalization routine. Defaults to
                                        SysBase->TaskExitCode.
       TASKTAG_STACKSIZE    (ULONG)   - Size of task's stack. Defaults to CPU-dependent
                                        value.
       TASKTAG_NAME         (STRPTR)  - A pointer to task name. The name will be copied.
       TASKTAG_USERDATA     (APTR)    - Anything. Will be written into tc_UserData.
       TASKTAG_PRI          (BYTE)    - Task's priority. Defaults to 0.
       TASKTAG_ARG1 ...
       TASKTAG_ARG8         (IPTR)    - Arguments (up to 8) which will be passed to task's
                                        entry function. The arguments are supplied in
                                        C-standard way.
       TASKTAG_FLAGS        (ULONG)   - Initial value for tc_Flags.
       TASKTAG_TASKMSGPORT  (struct MsgPort **)
                                      - Create a message port for the task and place its
                                        address into the location specified by ti_Data.
       TASKTAG_TCBEXTRASIZE (ULONG)   - Value which will be added to sizeof(struct Task)
                                        in order to determine final size of task structure.
                                        Can be used for appending user data to task structure.


Result
~~~~~~
::

     A pointer to the new task or NULL on failure.


Bugs
~~~~
::

     Value of TASKTAG_FLAGS is actually ignored.
     There are some more tags which are currently not implemented.



----------

NewMinList()
============

Synopsis
~~~~~~~~
::

 void NewMinList(
          struct MinList * list );

Function
~~~~~~~~
::

     Initialize a list. After that, you can use functions like
     AddHead(), AddTail() and Insert() on the list.


Inputs
~~~~~~
::

     list - the list to be initialized


Result
~~~~~~
::

     None.


Example
~~~~~~~
::

     See below.



See also
~~~~~~~~

NEWLIST() macro libamiga/NewList() 

----------

NewStackSwap()
==============

Synopsis
~~~~~~~~
::

 IPTR NewStackSwap(
          struct StackSwapStruct * sss,
          LONG_FUNC entry,
          struct StackSwapArgs * args );

Function
~~~~~~~~
::

     Calls a function with a new stack.


Inputs
~~~~~~
::

     sss     -   A structure containing the values for the upper, lower
                 and current bounds of the stack you wish to use.
     entry   -   Address of the function to call.
     args    -   A structure (actually an array) containing up to 8
                 function arguments. May be NULL.


Result
~~~~~~
::

     The value returned by your function.


Notes
~~~~~
::

     This function is mostly compatible with MorphOS's NewPPCStackSwap()
     function.


Bugs
~~~~
::

     Do not attempt to pass in a prebuilt stack - it will be erased.



See also
~~~~~~~~

`StackSwap()`_ 

----------

ObtainQuickVector()
===================

Synopsis
~~~~~~~~
::

 ULONG ObtainQuickVector(
          APTR interruptCode );


----------

ObtainSemaphoreList()
=====================

Synopsis
~~~~~~~~
::

 void ObtainSemaphoreList(
          struct List * sigSem );

Function
~~~~~~~~
::

     This function takes a list of semaphores and locks all of them at
     once. It is only possible for one task to attempt to lock all the
     semaphores at once (since it uses the ss_MultipleLink field), so
     you will need to protect the entire list (with another semaphore
     perhaps?).

     If somebody attempts to lock more than one semaphore on this list
     with ObtainSemaphore() it is possible for a deadlock to occur due
     to two tasks waiting for a semaphore that the other has obtained.


Inputs
~~~~~~
::

     sigSem - pointer to list full of semaphores


Result
~~~~~~
::

     The entire semaphore list will be locked.



----------

ObtainSemaphoreShared()
=======================

Synopsis
~~~~~~~~
::

 void ObtainSemaphoreShared(
          struct SignalSemaphore * sigSem );

Function
~~~~~~~~
::

     Get a shared lock on a semaphore. If the lock cannot be obtained
     immediately this function waits. There may be more than one shared
     locks at the same time but only one exclusive one. An exclusive
     lock prevents shared locks. Shared locks are released with
     ReleaseSemaphore().


Inputs
~~~~~~
::

     sigSem - Pointer to semaphore structure


Notes
~~~~~
::

     This function preserves all registers.



See also
~~~~~~~~

`ReleaseSemaphore()`_ 

----------

OldOpenLibrary()
================

Synopsis
~~~~~~~~
::

 struct Library * OldOpenLibrary(
          UBYTE * libName );

Function
~~~~~~~~
::

     This is the same function as OpenLibrary(), only that it uses 0 as
     version number. This function is obsolete. Don't use it.



See also
~~~~~~~~

`OpenLibrary()`_ 

----------

OpenDevice()
============

Synopsis
~~~~~~~~
::

 LONG OpenDevice(
          CONST_STRPTR devName,
          IPTR unitNumber,
          struct IORequest * iORequest,
          ULONG flags );

Function
~~~~~~~~
::

     Tries to open a device and fill the iORequest structure.  An error
     is returned if this fails, 0 if all went well.

     If the device doesn't exist in the current system device list, then
     first the system ROMtag module list, then if the DOS is running,
     then the DEVS: directory will be tried.


Inputs
~~~~~~
::

     devName    - Pointer to the devices's name.
     unitNumber - The unit number. Most often 0. In some special cases this can be
                  a pointer to something (device-dependent).
     iORequest  - Pointer to device specific information.
                  Will be filled out by the device.
                  Must lie in public (or at least shared) memory.
     flags      - Some flags to give to the device.


Result
~~~~~~
::

     Error code or 0 if all went well. The same value can be found
     in the io_Error field.


Notes
~~~~~
::

     Return type is internally extended to LONG in all existing official ROMs
     (EXT.W D0 + EXT.L D0) DoIO() and WaitIO() do the same.
     Many programs assume LONG return code, even some WB utilities.



See also
~~~~~~~~

`OpenDevice()`_ 

----------

OpenLibrary()
=============

Synopsis
~~~~~~~~
::

 struct Library * OpenLibrary(
          CONST_STRPTR libName,
          ULONG version );

Function
~~~~~~~~
::

     Opens a library given by name and revision. If the library does not
     exist in the current system shared library list, the first the
     system ROMTag module list is tried. If this fails, and the DOS is
     running, then the library will be loaded from disk.


Inputs
~~~~~~
::

     libName - Pointer to the library's name.
     version - the library's version number.


Result
~~~~~~
::

     Pointer to library structure or NULL.



See also
~~~~~~~~

`CloseLibrary()`_ 

----------

OpenResource()
==============

Synopsis
~~~~~~~~
::

 APTR OpenResource(
          CONST_STRPTR resName );

Function
~~~~~~~~
::

     Return a pointer to a previously installed resource addressed by
     name.  If this name can't be found NULL is returned.


Inputs
~~~~~~
::

     resName - Pointer to the resource's name.


Result
~~~~~~
::

     Pointer to resource or NULL.



See also
~~~~~~~~

`AddResource()`_ `RemResource()`_ 

----------

Permit()
========

Synopsis
~~~~~~~~
::

 void Permit();

Function
~~~~~~~~
::

     This function will reactivate the task dispatcher after a call
     to Forbid(). Note that calls to Forbid() nest, and for every
     call to Forbid() you need a matching call to Permit().


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     Multitasking will be re-enabled.


Example
~~~~~~~
::

     It is generally not necessary/desirable to use Forbid()/Permit()
     in most userspace code.


Notes
~~~~~
::

     This function preserves all registers.

     To prevent deadlocks calling Wait() in forbidden state breaks
     the forbid - thus taskswitches may happen again.


Bugs
~~~~
::

     The only architecture that you can rely on the registers being
     saved is on the Motorola mc68000 family.



See also
~~~~~~~~

`Forbid()`_ `Disable()`_ `Enable()`_ `Wait()`_ 

----------

Procure()
=========

Synopsis
~~~~~~~~
::

 ULONG Procure(
          struct SignalSemaphore  * sigSem,
          struct SemaphoreMessage * bidMsg );

Function
~~~~~~~~
::

     Tries to get a lock on a semaphore in an asynchronous manner.
     If the semaphore is not free this function will not wait but
     just post a request to the semaphore. As soon as the semaphore is
     available the bidMsg will return and make you owner of the semaphore.


Inputs
~~~~~~
::

     sigSem - pointer to semaphore structure
     bidMsg - pointer to a struct SemaphoreMessage. This should lie in
              public or at least shared memory.


Result
~~~~~~
::

     Principly none. Don't know. Just ignore it.


Notes
~~~~~
::

     Locks obtained with Procure() must be released with Vacate().



See also
~~~~~~~~

`Vacate()`_ 

----------

PutMsg()
========

Synopsis
~~~~~~~~
::

 void PutMsg(
          struct MsgPort * port,
          struct Message * message );

Function
~~~~~~~~
::

     Sends a message to a given message port. Messages are not copied
     from one task to another but must lie in shared memory instead.
     Therefore the owner of the message may generally not reuse it before
     it is returned. But this depends on the two tasks sharing the message.


Inputs
~~~~~~
::

     port    - Pointer to messageport.
     message - Pointer to message.


Notes
~~~~~
::

     It is legal to send a message from within interrupts.

     Messages may either trigger a signal at the owner of the messageport
     or raise a software interrupt, depending on port->mp_Flags&PF_ACTION.



See also
~~~~~~~~

`WaitPort()`_ `GetMsg()`_ 

----------

RawDoFmt()
==========

Synopsis
~~~~~~~~
::

 RAWARG RawDoFmt(
          CONST_STRPTR FormatString,
          RAWARG DataStream,
          VOID_FUNC PutChProc,
          APTR PutChData );

Function
~~~~~~~~
::

     printf-style formatting function with callback hook.


Inputs
~~~~~~
::

     FormatString - Pointer to the format string with any of the following
                    DataStream formatting options allowed:

                    %[leftalign][minwidth.][maxwidth][size][type]

                    leftalign - '-' means align left. Default: align right.
                    minwidth  - minimum width of field. Defaults to 0.
                    maxwidth  - maximum width of field (for strings only).
                                Defaults to no limit.

                    size      - 'l' means LONG. 'll' or 'L' means QUAD
                                (AROS extension). Defaults to WORD, if
                                nothing is specified.

                    type      - 'b' BSTR. It will use the internal representation
                                    of the BSTR defined by the ABI.
                                'c' single character.
                                'd' signed decimal number.
                                's' C string. NULL terminated.
                                'u' unsigned decimal number.
                                'x' unsigned hexadecimal number.
                                'P' pointer. Size depends on the architecture.
                                'p' The same as 'P', for AmigaOS v4 compatibility.

     DataStream   - Pointer to a zone of memory containing the data. Data has to be
                    WORD aligned.

     PutChProc    - Callback function. Called for each character, including
                    the NULL terminator. The fuction is called as follows:

                    AROS_UFC2(void, PutChProc,
                              AROS_UFCA(UBYTE, char,      D0),
                              AROS_UFCA(APTR , PutChData, A3));
                 
                    Additionally, PutChProc can be set to one of the following
                    magic values:

                      RAWFMTFUNC_STRING - Write output to string buffer pointed
                                          to by PutChData which is incremented
                                          every character.
                      RAWFMTFUNC_SERIAL - Write output to debug output. PutChData
                                          is ignored and not touched.
                      RAWFMTFUNC_COUNT  - Count number of characters in the result.
                                          PutChData is a pointer to ULONG which
                                          is incremented every character. Initial
                                          value of the counter is kept as it is.

                    If you want to be compatible with AmigaOS you
                    should check that exec.library has at least version 45.

     PutChData    - Data propagated to each call of the callback hook.


Result
~~~~~~
::

     Pointer to the rest of the DataStream.


Example
~~~~~~~
::

     Build a sprintf style function:

         void my_sprintf(UBYTE *buffer, UBYTE *format, ...);

         static void callback(UBYTE chr __reg(d0), UBYTE **data __reg(a3))
         {
            *(*data)++=chr;
         }

         void my_sprintf(UBYTE *buffer, UBYTE *format, ...)
         {
             AROS_SLOWSTACKFORMAT_PRE(format)
             RawDoFmt(format, AROS_SLOWSTACKFORMAT_ARG(format), &callback, &buffer);
             AROS_SLOWSTACKFORMAT_POST(format)
         }

     The above example uses AROS_SLOWSTACKFORMAT_* macros in the function
     in order to make sure that arguments are all passed on
     the stack on all architectures. The alternative is to use
     VNewRawDoFmt() function which takes va_list instead of array
     DataStream.


Notes
~~~~~
::

     The field size defaults to WORD which may be different from the
     default integer size of the compiler. If you don't take care about
     this the result will be messy.
     
     There are different solutions for GCC:
     - Define Datastream between #pragma pack(2) / #pragma pack().
     - Use __attribute__((packed)) for Datastream.
     - Only use type of LONG/ULONG for integer variables. Additionally only use
       %ld/%lu in FormatString.


Bugs
~~~~
::

     PutChData cannot be modified from the callback hook on non-m68k
     systems.



----------

ReadGayle()
===========

Synopsis
~~~~~~~~
::

 ULONG ReadGayle();

Function
~~~~~~~~
::

 Gets the Gayle ID


Inputs
~~~~~~
::

     None.



----------

ReleaseSemaphore()
==================

Synopsis
~~~~~~~~
::

 void ReleaseSemaphore(
          struct SignalSemaphore * sigSem );

Function
~~~~~~~~
::

     Releases a lock on a semaphore obtained with either ObtainSemaphore(),
     ObtainSemaphoreShared(), AttemptSemaphore or AttemptSemaphoreShared().
     Each call to one of those functions must be accompanied by one call
     to ReleaseSemaphore().


Inputs
~~~~~~
::

     sigSem - pointer to semaphore structure


Notes
~~~~~
::

     This function preserves all registers.



----------

ReleaseSemaphoreList()
======================

Synopsis
~~~~~~~~
::

 void ReleaseSemaphoreList(
          struct List * sigSem );

Function
~~~~~~~~
::

     This function releases all semaphores in the list at once.


Inputs
~~~~~~
::

     sigSem - pointer to list full of semaphores



----------

RemDevice()
===========

Synopsis
~~~~~~~~
::

 void RemDevice(
          struct Device * device );

Function
~~~~~~~~
::

     Calls the given device's expunge vector, thus trying to delete it.
     The device may refuse to do so and still be open after this call.


Inputs
~~~~~~
::

     device - Pointer to the device structure.



See also
~~~~~~~~

`AddDevice()`_ `OpenDevice()`_ `CloseDevice()`_ 

----------

RemHead()
=========

Synopsis
~~~~~~~~
::

 struct Node * RemHead(
          struct List * list );

Function
~~~~~~~~
::

     Remove the first node from a list.


Inputs
~~~~~~
::

     list - Remove the node from this list


Result
~~~~~~
::

     The node that has been removed.


Example
~~~~~~~
::

     struct List * list;
     struct Node * head;

     // Remove node and return it
     head = RemHead (list);



----------

RemIntServer()
==============

Synopsis
~~~~~~~~
::

 void RemIntServer(
          ULONG intNumber,
          struct Interrupt * interrupt );


----------

RemLibrary()
============

Synopsis
~~~~~~~~
::

 void RemLibrary(
          struct Library * library );

Function
~~~~~~~~
::

     Calls the given library's expunge vector, thus trying to delete it.
     The library may refuse to do so and still be open after this call.


Inputs
~~~~~~
::

     library - Pointer to the library structure.



See also
~~~~~~~~

`AddLibrary()`_ `MakeLibrary()`_ `MakeFunctions()`_ `InitStruct()`_ `SumLibrary()`_ 

----------

RemMemHandler()
===============

Synopsis
~~~~~~~~
::

 void RemMemHandler(
          struct Interrupt * memHandler );

Function
~~~~~~~~
::

     Remove some function added with AddMemHandler again.


Inputs
~~~~~~
::

     memHandler - The same Interrupt structure you gave to AddMemHandler().



----------

Remove()
========

Synopsis
~~~~~~~~
::

 void Remove(
          struct Node * node );

Function
~~~~~~~~
::

     Remove a node from a list.


Inputs
~~~~~~
::

     node - This node to be removed.


Example
~~~~~~~
::

     struct Node * node;

     // Remove node
     Remove (node);


Notes
~~~~~
::

     There is no need to specify the list but the node must be in
     a list !



----------

RemPort()
=========

Synopsis
~~~~~~~~
::

 void RemPort(
          struct MsgPort * port );

Function
~~~~~~~~
::

     Remove a public port from the public port list to make it private
     again. Any further attempts to find this port in the public port
     list will fail.


Inputs
~~~~~~
::

     port - Pointer to messageport structure.



----------

RemResetCallback()
==================

Synopsis
~~~~~~~~
::

 void RemResetCallback(
          struct Interrupt * interrupt );

Function
~~~~~~~~
::

     Remove reset handler previously installed using AddResetCallBack()


Inputs
~~~~~~
::

     interrupt - A pointer to an Interrupt structure


Result
~~~~~~
::

     None.


Notes
~~~~~
::

     This function is compatible with AmigaOS v4.



----------

RemResource()
=============

Synopsis
~~~~~~~~
::

 void RemResource(
          APTR resource );

Function
~~~~~~~~
::

     Removes a resource from the system resource list.


Inputs
~~~~~~
::

     resource - Pointer to the resource.



See also
~~~~~~~~

`AddResource()`_ `OpenResource()`_ 

----------

RemSemaphore()
==============

Synopsis
~~~~~~~~
::

 void RemSemaphore(
          struct SignalSemaphore * sigSem );

Function
~~~~~~~~
::

     Removes a semaphore from the system public semaphore list.


Inputs
~~~~~~
::

     sigSem - Pointer to semaphore structure


Notes
~~~~~
::

     Semaphores are shared between the tasks that use them and must
     therefore lie in public (or at least shared) memory.



----------

RemTail()
=========

Synopsis
~~~~~~~~
::

 struct Node * RemTail(
          struct List * list );

Function
~~~~~~~~
::

     Remove the last node from a list.


Inputs
~~~~~~
::

     list - Remove the node from this list


Result
~~~~~~
::

     The node that has been removed.


Example
~~~~~~~
::

     struct List * list;
     struct Node * tail;

     // Remove node and return it
     tail = RemTail (list);



----------

RemTask()
=========

Synopsis
~~~~~~~~
::

 void RemTask(
          struct Task * task );

Function
~~~~~~~~
::

     Remove a task from the task lists. All memory in the tc_MemEntry list
     is freed and a reschedule is done. It's safe to call RemTask() outside
     Forbid() or Disable().

     This function is one way to get rid of the current task. The other way
     is to fall through the end of the entry point.


Inputs
~~~~~~
::

     task - Task to be removed. NULL means current task.



See also
~~~~~~~~

`AddTask()`_ 

----------

ReplyMsg()
==========

Synopsis
~~~~~~~~
::

 void ReplyMsg(
          struct Message * message );

Function
~~~~~~~~
::

     Send a message back to where it came from. It's generally not
     wise to access the fields of a message after it has been replied.


Inputs
~~~~~~
::

     message - a message got with GetMsg().



See also
~~~~~~~~

`WaitPort()`_ `GetMsg()`_ `PutMsg()`_ 

----------

Reschedule()
============

Synopsis
~~~~~~~~
::

 void Reschedule();

Function
~~~~~~~~
::

     Give up the CPU time to other tasks (if there are any).


Inputs
~~~~~~
::

     None


Result
~~~~~~
::

     None


Notes
~~~~~
::

     This function was private in AmigaOS(tm) up to v3.1. There's no guarantee
     that it will continue to exist in other systems.



----------

RestoreTaskStorage()
====================

Synopsis
~~~~~~~~
::

 void RestoreTaskStorage();

Function
~~~~~~~~
::

     This function restores the current state of the task storage slots.


Inputs
~~~~~~
::

     id - ID returned from SaveTaskStorage() referring to the state.


Result
~~~~~~
::

     None.



See also
~~~~~~~~

`SaveTaskStorage()`_ 

----------

SaveTaskStorage()
=================

Synopsis
~~~~~~~~
::

 APTR SaveTaskStorage();

Function
~~~~~~~~
::

     This function remembers the current state of the task storage slots.
     An ID will be returned with which the current state can be restored
     using RestoreTaskStorage(). NULL is returned when not enough memory
     is available.


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     id - ID for use with RestoreTaskStorage(), or NULL.



See also
~~~~~~~~

`RestoreTaskStorage()`_ 

----------

Schedule()
==========

Synopsis
~~~~~~~~
::

 void Schedule();

Function
~~~~~~~~
::

     PRIVATE architecture specific routine for relinquishing CPU time


Inputs
~~~~~~
::

     None


Result
~~~~~~
::

     None


Notes
~~~~~
::

     This function was private in AmigaOS(tm) up to v3.1. There's no guarantee
     that it will continue to exist in other systems.



----------

SendIO()
========

Synopsis
~~~~~~~~
::

 void SendIO(
          struct IORequest * iORequest );

Function
~~~~~~~~
::

     Start an asynchronous I/O request by calling the device's BeginIO()
     vector. After sending the messages asynchronously you can wait for
     the message to be replied at the I/O reply port.


Inputs
~~~~~~
::

     iORequest - Pointer to iorequest structure.



See also
~~~~~~~~

`OpenDevice()`_ `CloseDevice()`_ `DoIO()`_ `CheckIO()`_ `AbortIO()`_ `WaitIO()`_ 

----------

SetExcept()
===========

Synopsis
~~~~~~~~
::

 ULONG SetExcept(
          ULONG newSignals,
          ULONG signalSet );

Function
~~~~~~~~
::

     Change the mask of signals causing a task exception.


Inputs
~~~~~~
::

     newSignals - Set of signals causing the exception.
     signalSet  - Mask of affected signals.


Result
~~~~~~
::

     Old mask of signals causing a task exception.



See also
~~~~~~~~

`AllocSignal()`_ `FreeSignal()`_ `Wait()`_ `SetSignal()`_ `Signal()`_ 

----------

SetFunction()
=============

Synopsis
~~~~~~~~
::

 APTR SetFunction(
          struct Library * library,
          LONG funcOffset,
          APTR newFunction );

Function
~~~~~~~~
::

     Replaces a certain jumptable entry with another one. This function only
     Forbid()s taskswitching but doesn't Disable() interrupts. You have
     to do your own arbitration for functions which are callable from
     interrupts.


Inputs
~~~~~~
::

     library     - Pointer to library structure.
     funcOffset  - Offset of the jumpvector from the library base address in
                   bytes. It's the negative LVO (library vector offset)
                   multiplied with LIB_VECTSIZE.
     newFunction - New jumptable entry (pointer to the new function).


Result
~~~~~~
::

     Old jumptable entry (pointer to the old function).


Example
~~~~~~~
::

     Patch of the function Open() from dos.library:
     You can find the LVO of 5 in clib/dos_protos.h.
     SetFunction(DOSBase, -5 * LIB_VECTSIZE, NewOpen);
     NewOpen must be prepared with AROS_UFH macros.


Notes
~~~~~
::

     While it's more or less safe to patch a library vector with
     SetFunction() it's not possible to safely remove the patch later.
     So don't use this function if it can be avoided.


Bugs
~~~~
::

     None.



See also
~~~~~~~~

`MakeLibrary()`_ `MakeFunctions()`_ `SumLibrary()`_ 

----------

SetIntVector()
==============

Synopsis
~~~~~~~~
::

 struct Interrupt * SetIntVector(
          ULONG intNumber,
          struct Interrupt * interrupt );


----------

SetSignal()
===========

Synopsis
~~~~~~~~
::

 ULONG SetSignal(
          ULONG newSignals,
          ULONG signalSet );

Function
~~~~~~~~
::

     Change or read the set of signals sent to the current task.


Inputs
~~~~~~
::

     newSignals - New values for the signals.
     signalSet  - Mask of signals affected by 'newSignals'.


Result
~~~~~~
::

     Old signal set.



See also
~~~~~~~~

`AllocSignal()`_ `FreeSignal()`_ `Wait()`_ `Signal()`_ `SetExcept()`_ 

----------

SetSR()
=======

Synopsis
~~~~~~~~
::

 ULONG SetSR(
          ULONG newSR,
          ULONG mask );

Function
~~~~~~~~
::

     Read/Modify the CPU status register in an easy way. Only the bits
     set it the mask parameter will be changed.

     The bits in the register mapped to those of the Motorola MC680x0
     family of microprocessors.


Inputs
~~~~~~
::

     newSR   -   The new contents of the status register.
     mask    -   Mask of bits to change.


Result
~~~~~~
::

     The old contents of the status register or ~0UL if this function
     is not implemented.


Example
~~~~~~~
::

     You can read the status register by calling SetSR(0,0).


Notes
~~~~~
::

     This function is of limited use.


Bugs
~~~~
::

     This function may do nothing on non-mc680x0 systems.



----------

SetTaskPri()
============

Synopsis
~~~~~~~~
::

 BYTE SetTaskPri(
          struct Task * task,
          LONG priority );

Function
~~~~~~~~
::

     Change the priority of a given task. As a general rule the higher
     the priority the more CPU time a task gets. Useful values are within
     -127 to 5.


Inputs
~~~~~~
::

     task     - Pointer to task structure.
     priority - New priority of the task.


Result
~~~~~~
::

     Old task priority.



----------

SetTaskStorageSlot()
====================

Synopsis
~~~~~~~~
::

 BOOL SetTaskStorageSlot();

Function
~~~~~~~~
::

     Puts a new value in a task storage slot. If necessary, the number of
     task storage slots will be increased.


Inputs
~~~~~~
::

     id - slot ID returned from AllocTaskStorageSlot().
     value - value to store in the slot.


Result
~~~~~~
::

     success - TRUE if the value was successfully stored.



See also
~~~~~~~~

`AllocTaskStorageSlot()`_ `FreeTaskStorageSlot()`_ `GetTaskStorageSlot()`_ 

----------

ShutdownA()
===========

Synopsis
~~~~~~~~
::

 ULONG ShutdownA(
          ULONG action );
 
 ULONG Shutdown(
          TAG tag, ... );

Function
~~~~~~~~
::

     This function attempts to shut down registered handlers
     before rebooting the system, or entering a powered off state.


Inputs
~~~~~~
::

     action - which process to perform:
      * SD_ACTION_POWEROFF   - power off/halt the hardware.
      * SD_ACTION_COLDREBOOT - cold reboot the hardware.
      * SD_ACTION_WARMREBOOT - soft reboot the operating system.


Result
~~~~~~
::

     This function does not return in case of success. Otherwise it returns
     zero.


Notes
~~~~~
::

     It can be quite harmful to call this function. It may be possible that
     you will lose data from other tasks not having saved, or disk buffers
     not being flushed. Plus you could annoy the (other) users.



See also
~~~~~~~~

`ColdReboot()`_ 

----------

Signal()
========

Synopsis
~~~~~~~~
::

 void Signal(
          struct Task * task,
          ULONG signalSet );

Function
~~~~~~~~
::

     Send some signals to a given task. If the task is currently waiting
     on these signals, has a higher priority as the current one and if
     taskswitches are allowed the new task begins to run immediately.


Inputs
~~~~~~
::

     task      - Pointer to task structure.
     signalSet - The set of signals to send to the task.


Notes
~~~~~
::

     This function may be used from interrupts.



See also
~~~~~~~~

`AllocSignal()`_ `FreeSignal()`_ `Wait()`_ `SetSignal()`_ `SetExcept()`_ 

----------

StackSwap()
===========

Synopsis
~~~~~~~~
::

 void StackSwap(
          struct StackSwapStruct * sss );

Function
~~~~~~~~
::

     Changes the stack used by a task. The StackSwapStruct will contain
     the value of the old stack such that the stack can be reset to the
     previous version by another call to StackSwap().

     When the stack is swapped, the data on the stack(s) will not be
     altered, so the stack may not be set up for you. It is generally
     required that you replace your stack before exiting from the
     current stack frame (procedure, function call etc.).


Inputs
~~~~~~
::

     sss     -   A structure containing the values for the upper, lower
                 and current bounds of the stack you wish to use. The
                 values will be replaced by the current values and you
                 can restore the values later.


Result
~~~~~~
::

     The program will be running on a new stack and sss will contain
     the old stack.

     Calling StackSwap() twice consecutively will effectively do
     nothing.


Notes
~~~~~
::

     Returning from the function that you call StackSwap() in can have
     unexpected results.

     Use of StackSwap() is deprecated on AROS; NewStackSwap() should
     be used instead. StackSwap() is only retained to provide backwards
     compatibility. On some hosted versions with strict stack checking use
     of StackSwap() may cause problems.
     By default StackSwap() will not be defined and you have to
     #define __AROS_GIMME_DEPRECATED_STACKSWAP__ before including
     <proto/exec.h>. As said above it is highly advised to change code
     to use NewStackSwap() and not define __AROS_GIMME_DEPRECATED_STACKSWAP__



See also
~~~~~~~~

`AddTask()`_ `RemTask()`_ `NewStackSwap()`_ 

----------

SumKickData()
=============

Synopsis
~~~~~~~~
::

 ULONG SumKickData();


----------

SumLibrary()
============

Synopsis
~~~~~~~~
::

 void SumLibrary(
          struct Library * library );

Function
~~~~~~~~
::

     Builds the checksum over a given library's jumptable and either puts
     it into the library->lib_Sum field (if the library is marked as changed)
     or compares it with this field and Alert()s at mismatch.


Inputs
~~~~~~
::

     library - Pointer to library structure.



See also
~~~~~~~~

`AddLibrary()`_ `RemLibrary()`_ `MakeLibrary()`_ `MakeFunctions()`_ `InitStruct()`_ 

----------

SuperState()
============

Synopsis
~~~~~~~~
::

 APTR SuperState();

Function
~~~~~~~~
::

     Enter supervisor mode (like Supervisor()), but return on the user
     stack. This will mean that the user stack variables are still there.
     A call to UserState() will end this mode.


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     The old supervisor stack. This must be passed to UserState(). If the
     processor was already in supervisor mode, then this function will
     return NULL. In that case do NOT call UserState().


Notes
~~~~~
::

     This is not a good function to use, it has limited scope, and will
     probably be even less useful in the future.


Bugs
~~~~
::

     You can easily cause your system to cease operating normally.



See also
~~~~~~~~

`Supervisor()`_ `UserState()`_ 

----------

Supervisor()
============

Synopsis
~~~~~~~~
::

 IPTR Supervisor(
          void * userFunction );

Function
~~~~~~~~
::

     Supervisor will allow a short privileged instruction sequence to
     be called from user mode. This has very few uses, and it is probably
     better to use any system supplied method to do anything.

     The function supplied will be called as if it was a system interrupt,
     notably this means that you must *NOT* make any system calls or
     use any system data structures, and on certain systems you must
     use special methods to leave the code.

     The code will not be passed any parameters. However it has access to all
     CPU registers.


Inputs
~~~~~~
::

     userFunction -  The address of the code you want called in supervisor
                     mode.


Result
~~~~~~
::

     The code will be called.


Notes
~~~~~
::

     On some architectures this function is impossible or infeasible to implement.
     In this case it throws a recoverable alert.

     Currently this function works only on x86 and PowerPC native kickstarts.


Bugs
~~~~
::

     You can very easily make the system unusable with this function.
     In fact it is recommended that you do not use it at all.



See also
~~~~~~~~

`SuperState()`_ `UserState()`_ 

----------

Switch()
========

Synopsis
~~~~~~~~
::

 void Switch();

Function
~~~~~~~~
::

     PRIVATE function to force a task switch to the next runnable task


Inputs
~~~~~~
::

     None


Result
~~~~~~
::

     None


Notes
~~~~~
::

     This function was private in AmigaOS(tm) up to v3.1.
     There's no guarantee that it will continue to exist in other systems.



----------

TypeOfMem()
===========

Synopsis
~~~~~~~~
::

 ULONG TypeOfMem(
          APTR address );

Function
~~~~~~~~
::

     Return type of memory at a given address or 0 if there is no memory
     there.


Inputs
~~~~~~
::

     address - Address to test


Result
~~~~~~
::

     The memory flags you would give to AllocMem().



----------

UserState()
===========

Synopsis
~~~~~~~~
::

 void UserState(
          APTR sysStack );

Function
~~~~~~~~
::

     Return to user mode after a call to SuperState().


Inputs
~~~~~~
::

     sysStack    -   The return value from SuperState()


Result
~~~~~~
::

     The system will be back to normal.



See also
~~~~~~~~

`SuperState()`_ `Supervisor()`_ 

----------

Vacate()
========

Synopsis
~~~~~~~~
::

 void Vacate(
          struct SignalSemaphore  * sigSem,
          struct SemaphoreMessage * bidMsg );

Function
~~~~~~~~
::

     Release a lock obtained with Procure. This will even work if the
     message is not yet replied - the request will be cancelled and the
     message replied. In any case the ssm_Semaphore field will be set to
     NULL.


Inputs
~~~~~~
::

     sigSem - Pointer to semaphore structure.
     bidMsg - Pointer to struct SemaphoreMessage.



See also
~~~~~~~~

`Procure()`_ 

----------

VNewRawDoFmt()
==============

Synopsis
~~~~~~~~
::

 STRPTR VNewRawDoFmt(
          CONST_STRPTR FormatString,
          VOID_FUNC PutChProc,
          APTR PutChData,
          va_list DataStream );

Function
~~~~~~~~
::

     printf-style formatting function with callback hook and C-style
     DataStream.


Inputs
~~~~~~
::

     FormatString - Pointer to the format string with any of the following
                    DataStream formatting options allowed:

                    %[leftalign][minwidth.][maxwidth][size][type]

                    leftalign - '-' means align left. Default: align right.
                    minwidth  - minimum width of field. Defaults to 0.
                    maxwidth  - maximum width of field (for strings only).
                                Defaults to no limit.

                    size      - 'l' can be used, but effectively ignored for
                                backwards compatibility with original RawDoFmt().
                                In C arguments are always at least int-sized.

                    type      - 'b' BSTR. It will use the internal representation
                                    of the BSTR defined by the ABI.
                                'c' single character.
                                'd' signed decimal number.
                                's' C string. NULL terminated.
                                'u' unsigned decimal number.
                                'x' unsigned hexdecimal number.
                                'P' pointer. Size depends on the architecture.
                                'p' The same as 'P', for AmigaOS v4 compatibility.

     PutChProc    - Callback function. Called for each character, including
                    the NULL terminator. The function should be declared as
                    follows:

                    APTR PutChProc(APTR PutChData, UBYTE char);

                    The function should return new value for PutChData variable.

                    Additionally, PutChProc can be set to one of the following
                    magic values:

                      RAWFMTFUNC_STRING - Write output to string buffer pointed
                                          to by PutChData which is incremented
                                          every character.
                      RAWFMTFUNC_SERIAL - Write output to debug output. PutChData
                                          is ignored and not touched.
                      RAWFMTFUNC_COUNT  - Count number of characters in the result.
                                          PutChData is a pointer to ULONG which
                                          is incremented every character. Initial
                                          value of the counter is kept as it is.

     PutChData    - Data propagated to each call of the callback hook.

     DataStream   - C-style data stream (va_list variable)


Result
~~~~~~
::

     Final PutChData value.


Example
~~~~~~~
::

     Build a sprintf style function:

         void my_sprintf(UBYTE *buffer, UBYTE *format, ...)
         {
             va_list args;
             
             va_start(args, format);
             VNewRawDoFmt(format, RAWFMTFUNC_STRING, buffer, args);
             va_end(args);
         }



----------

Wait()
======

Synopsis
~~~~~~~~
::

 ULONG Wait(
          ULONG signalSet );

Function
~~~~~~~~
::

     Wait until some signals are sent to the current task. If any signal
     of the specified set is already set when entering this function it
     returns immediately. Since almost any event in the OS can send a
     signal to your task if you specify it to do so signals are a very
     powerful mechanism.


Inputs
~~~~~~
::

     signalSet - The set of signals to wait for.


Result
~~~~~~
::

     The set of active signals.


Notes
~~~~~
::

     Naturally it's not allowed to wait in supervisor mode.

     Calling Wait() breaks an active Disable() or Forbid().



See also
~~~~~~~~

`Signal()`_ `SetSignal()`_ `AllocSignal()`_ `FreeSignal()`_ 

----------

WaitIO()
========

Synopsis
~~~~~~~~
::

 LONG WaitIO(
          struct IORequest * iORequest );

Function
~~~~~~~~
::

     Waits until the I/O request is completed and removes it from the
     reply port. If the message is already done when calling this function,
     it doesn't wait but just removes the message.


Inputs
~~~~~~
::

     iORequest - Pointer to iorequest structure.


Result
~~~~~~
::

     Error state of I/O request.


Notes
~~~~~
::

     OpenDevice() notes explain LONG return type.



See also
~~~~~~~~

`OpenDevice()`_ `CloseDevice()`_ `DoIO()`_ `SendIO()`_ `AbortIO()`_ `CheckIO()`_ 

----------

WaitPort()
==========

Synopsis
~~~~~~~~
::

 struct Message * WaitPort(
          struct MsgPort * port );

Function
~~~~~~~~
::

     Wait until a message arrives at the given port. If there is already
     a message in it this function returns immediately.


Inputs
~~~~~~
::

     port    - Pointer to messageport.


Result
~~~~~~
::

     Pointer to the first message that arrived at the port. The message
     is _not_ removed from the port. GetMsg() does this for you.



See also
~~~~~~~~

`WaitPort()`_ `GetMsg()`_ 

