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.

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.

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);

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.

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.

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.

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.

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

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.

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.

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

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.

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

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

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().

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.

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.

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).

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).

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).

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.

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);

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).

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.

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.

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().

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.

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.

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.

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().

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().

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.

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.

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.

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.

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.

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.

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.

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.

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.

(*) On EXECSMP builds, Disable() only aplies to the processor
    it is called from (and needs to be re-enabled there also)
    Data which needs to be protected from parallel access will
    also require a spinlock.

Bugs

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

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.

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.

(*) On EXECSMP builds, Enable() only applies to the processor
    it is called from. Data which needs to be protected from
    parallel access will also require a spinlock.

Bugs

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

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

On uniprocessor builds of AROS, it is generally not necessary/
desirable to use Forbid()/Permit() in most userspace code - however for
EXECSMP builds, you will need to protect spinlocks against
task switches on the local processor..

Notes

This function preserves all registers.

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

(*) On EXECSMP builds, Forbid() only aplies to the processor
    it is called from. Data which needs to be protected from
    parallel access will also require a spinlock.

Bugs

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

FreeEntry()

Synopsis

void FreeEntry(
         struct MemList * entry );

Function

Free some memory allocated with AllocEntry().

Inputs

entry - The MemList you got from 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

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

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.

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.

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

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.

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.

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);

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

On uniprocessor builds of AROS, it is generally not necessary/
desirable to use Forbid()/Permit() in most userspace code - however for
EXECSMP builds, you will need to protect spinlocks against
task switches on the local processor..

Notes

This function preserves all registers.

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

(*) On EXECSMP builds, Forbid() only aplies to the processor
    it is called from. Data which needs to be protected from
    parallel access will also require a spinlock.

Bugs

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

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().

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.

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.

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.

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.

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.

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().

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.

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.

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.

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.

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.

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.

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.

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.

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__

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.

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.

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.

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.

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.

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().

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.

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.