exec
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
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
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.
See also
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
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
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
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
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
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
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
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
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
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
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).
See also
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_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().
See also
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()
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.
See also
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()
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
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
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
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()
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
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
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
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.
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.
(*) 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().
See also
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
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
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
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
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
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
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
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.
See also
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
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
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.
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
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
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
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
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().
See also
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
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
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.
See also
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
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
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.
See also
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
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
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.
See also
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__
See also
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.
See also
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
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
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
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
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.