LONG AbortIO( struct IORequest * iORequest );
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.
iORequest - Pointer to iorequest structure.
Errorcode if the abort request failed, 0 if the abort request went well. io_Error will then be set to IOERR_ABORTED.
void AddDevice( struct Device * device );
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.
device - Pointer to a ready for use device structure.
void AddHead( struct List * list, struct Node * node );
Insert Node node as the first node of the list.
list - The list to insert the node into node - This node is to be inserted
None.
struct List * list; struct Node * pred; // Insert Node at top AddHead (list, node);
void AddIntServer( ULONG intNumber, struct Interrupt * interrupt );
This function also enables the corresponding chipset interrupt if run on a native Amiga.
void AddLibrary( struct Library * library );
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.
library - Pointer to a ready for use library structure.
Some old Amiga software expects that AddLibrary returns the library which was just added. When in binary compatibility mode AROS does this too.
void AddMemHandler( struct Interrupt * memHandler );
Add some function to be called if the system is low on memory.
memHandler - An Interrupt structure to add to the low memory handler list.
void AddMemList( IPTR size, ULONG attributes, LONG pri, APTR base, STRPTR name );
Add a new block of memory to the system memory lists.
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
No argument checking done.
void AddPort( struct MsgPort * port );
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.
port - Pointer to messageport structure.
BOOL AddResetCallback( struct Interrupt * interrupt );
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.
interrupt - A pointer to an Interrupt structure
TRUE for success, FALSE for failure
This function is compatible with AmigaOS v4.
void AddResource( APTR resource );
Adds a given resource to the system's resource list.
resource - Pointer to a ready for use resource.
void AddSemaphore( struct SignalSemaphore * sigSem );
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.
sigSem - Pointer to semaphore structure
Semaphores are shared between the tasks that use them and must therefore lie in public (or at least shared) memory.
void AddTail( struct List * list, struct Node * node );
Insert Node node at the end of a list.
list - The list to insert the node into node - This node is to be inserted
struct List * list; struct Node * pred; // Insert Node at end of the list AddTail (list, node);
APTR AddTask( struct Task * task, APTR initialPC, APTR finalPC );
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.
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.
The address of the new task or NULL if the operation failed.
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.
void Alert( ULONG alertNum );
Alerts the user of a serious system problem.
alertNum - This is a number which contains information about the reason for the call.
This routine may return, if the alert is not a dead-end one.
// Dead-End alert: 680x0 Access To Odd Address Alert (0x80000003);
You should not call this routine because it halts the machine, displays the message and then may reboot it.
APTR AllocAbs( IPTR byteSize, APTR location );
Allocate some memory from the system memory pool at a given address. The memory must be freed with FreeMem().
byteSize - Number of bytes you want to get location - Where you want to get the memory
A pointer to some memory including the requested bytes or NULL if the memory couldn't be allocated.
APTR Allocate( struct MemHeader * freeList, IPTR byteSize );
Allocate memory out of a private region handled by the MemHeader structure.
freeList - Pointer to the MemHeader structure which holds the memory byteSize - Number of bytes you want to get
A pointer to the number of bytes you wanted or NULL if the memory couldn't be allocated
#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); }
The memory is aligned to sizeof(struct MemChunk). All requests are rounded up to a multiple of that size.
Does not work with managed memory blocks because of backwards compatibility issues
struct MemList * AllocEntry( struct MemList * entry );
Allocate a number of memory blocks through a MemList structure.
entry - The MemList with one MemEntry for each block you want to get
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.
APTR AllocMem( IPTR byteSize, ULONG requirements );
Allocate some memory from the sytem memory pool with the given requirements.
byteSize - Number of bytes you want to get requirements - Type of memory
A pointer to the number of bytes you wanted or NULL if the memory couldn't be allocated
mytask=(struct Task *)AllocMem(sizeof(struct Task),MEMF_PUBLIC|MEMF_CLEAR);
The memory is aligned to sizeof(struct MemChunk). All requests are rounded up to a multiple of that size.
APTR AllocPooled( APTR poolHeader, IPTR memSize );
Allocate memory out of a private memory pool. The memory must be freed with FreePooled(), or by deallocating the entire pool with DeletePool().
poolHeader - Handle of the memory pool memSize - Number of bytes you want to get
A pointer to the number of bytes you wanted or NULL if the memory couldn't be allocated
BYTE AllocSignal( LONG signalNum );
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.
signalNum - Number of the signal to allocate or -1 if any signal will do.
Number of the signal or -1 if the signal couldn't be allocated.
LONG AllocTaskStorageSlot();
This function will allocate a slot in the taskstorage.
None.
slot - The allocated slot, or 0 if no slot could be allocated.
After this function SetTaskStorageSlot(slot) may be used to store values with each slot.
LONG AllocTrap( long trapNum );
APTR AllocVec( IPTR byteSize, ULONG requirements );
Allocate some memory from the sytem memory pool with the given requirements and without the need to memorize the actual size of the block.
byteSize - Number of bytes you want to get requirements - Type of memory
A pointer to the number of bytes you wanted or NULL if the memory couldn't be allocated
APTR AllocVecPooled( APTR poolHeader, IPTR memSize );
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().
poolHeader - Handle of the memory pool memSize - Number of bytes you want to get
A pointer to the number of bytes you wanted or NULL if the memory couldn't be allocated
ULONG AttemptSemaphore( struct SignalSemaphore * sigSem );
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.
sigSem - Pointer to semaphore structure.
TRUE if the semaphore could be obtained, FALSE otherwise.
The lock must be freed with ReleaseSemaphore().
ULONG AttemptSemaphoreShared( struct SignalSemaphore * sigSem );
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().
sigSem - pointer to semaphore structure
True if the semaphore could be obtained, false otherwise.
IPTR AvailMem( ULONG attributes );
Return either the total available memory or the largest available chunk of a given type of memory.
attributes - The same attributes you would give to AllocMem().
Either the total of the available memory or the largest chunk if MEMF_LARGEST is set in the attributes.
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));
Due to the nature of multitasking the returned value may already be obsolete when this function returns.
struct AVLNode * AVL_AddNode( struct AVLNode ** root, struct AVLNode * node, AVLNODECOMP func );
Add a new node to an AVL tree.
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.
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.
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)); }
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.
struct AVLNode * AVL_FindFirstNode( const struct AVLNode * Root );
Find the smallest node in an AVL tree.
Root - The root node of the AVL tree.
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.
See AVL_FindNextNodeByAddress()
AVL trees are balanced but not minimal. This operation must iterate the full depth of the tree on one side - approximately 1.44Log(N).
struct AVLNode * AVL_FindLastNode( const struct AVLNode * Root );
Find the largest node in an AVL tree.
Root - The root node of the AVL tree.
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.
See AVL_FindPrevNodeByAddress()
AVL trees are balanced but not minimal. This operation must iterate the full depth of the tree on one side - approximately 1.44Log(N).
struct AVLNode * AVL_FindNextNodeByAddress( const struct AVLNode * Node );
Perform an in-order traversal to the next node in the tree.
Node - The current node. The node must be present in the tree.
The next-greatest node in the tree, or NULL if Node was already the highest valued node in the tree.
... 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); }
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).
struct AVLNode * AVL_FindNextNodeByKey( const struct AVLNode * Root, AVLKEYCOMP func );
Find the node matching the key, or if such a node does not exist, then the node with the next-highest value.
Root - The root of the AVL tree. key - The key to search. func - The AVLKEYCOMP key comparision function for this tree.
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.
This is only O(1.44log(n)) in the worst case.
struct AVLNode * AVL_FindNode( const struct AVLNode * Root, AVLKEYCOMP func );
Find an entry in the AVL tree by key.
Root - The root of the AVL tree. key - The key to search. func - The AVLKEYCOMP key comparision function for this tree.
A pointer to the node matching key if it exists in the tree, or NULL if no such node exists.
node = (struct ExampleNode *)AVL_FindNode(root, "aros", ExampleKeyComp); if (node) printf(" `%s' occurs %d times\n", node->key, node->count);
struct AVLNode * AVL_FindPrevNodeByAddress( const struct AVLNode * Node );
Perform an inverse-order traversal to the previous node in the tree.
Node - The current node. The node must be present in the tree.
The next-least node in the tree, or NULL if Node was already the lowest valued node in the tree.
... 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); }
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).
struct AVLNode * AVL_FindPrevNodeByKey( const struct AVLNode * root, AVLKEYCOMP func );
Find the node matching the key, or if such a node does not exist, then the node with the next-lowest value.
Root - The root of the AVL tree. key - The key to search. func - The AVLKEYCOMP key comparision function for this tree.
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.
This is only O(1.44log(n)) in the worst case.
struct AVLNode * AVL_RemNodeByAddress( struct AVLNode ** Root, struct AVLNode * Node );
Remove a given node from the tree.
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.
Node is returned.
See AVL_FindNextNodeByAddress(), AVL_FindPrevNodeByAddress()
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.
struct AVLNode * AVL_RemNodeByKey( struct AVLNode ** root, AVLKEYCOMP func );
Looks up a node in the tree by key, and removes it if it is found.
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.
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.
See AVL_RemNodeByAddress().
void CacheClearE( APTR address, IPTR length, ULONG caches );
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
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.
The caches will be flushed.
It is possible that on some systems the entire cache will be even if this was not the specific request.
void CacheClearU();
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
The caches will be flushed.
It is possible that on some systems the entire cache will be even if this was not the specific request.
ULONG CacheControl( ULONG cacheBits, ULONG cacheMask );
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.
cacheBits - The new state of the bits cacheMask - A mask of the bits you wish to change.
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.
On CPU's without a separate instruction and data cache, these will be considered as equal. This function isn't implemented on all platforms.
void CachePostDMA( APTR address, ULONG * length, ULONG flags ); void CachePostDM( APTR address, ULONG * length, TAG tag, ... );
Do everything necessary to make CPU caches aware that a DMA has happened.
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.
DMA must follow a call to CachePreDMA() and must be followed by a call to CachePostDMA().
APTR CachePreDMA( APTR address, ULONG * length, ULONG flags ); APTR CachePreDM( APTR address, ULONG * length, TAG tag, ... );
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.
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.
The physical address in memory. *length contains the number of contiguous bytes in physical memory.
DMA must follow a call to CachePreDMA() and must be followed by a call to CachePostDMA().
void Cause( struct Interrupt * softint );
Schedule a software interrupt to occur. If the processor is currently running a user task, then the software interrupt will prempt 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.
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.
The software interrupt will be delivered, or queued for later delivery.
No bounds checking on the software interrupt priority is done. Passing a bad priority to the system can have a strange effect.
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.
struct IORequest * CheckIO( struct IORequest * iORequest );
Check if an I/O request is completed.
iORequest - Pointer to iorequest structure.
Pointer to the iorequest structure or NULL if the device is still at work.
void ChildFree( ULONG tid );
Clean up after a child process.
tid -- Id of the child to clean up. This is not the same as the Task pointer.
The child will be freed.
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.
ULONG ChildOrphan( ULONG tid );
ChildOrphan() will detach the specified task from the its parent task 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.
tid -- The ID of the task to orphan, or 0 for all tasks. Note that it is NOT the pointer to the task.
Will return 0 on success or CHILD_* on an error. The child/children will no longer participate in child task actions.
ULONG ChildStatus( ULONG tid );
Return the status of a child task. This allows the Task to determine whether a particular child task is still running or not.
tid -- The ID of the task to examine. Note that it is _NOT_ a task pointer.
One of the CHILD_* values.
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.
IPTR ChildWait( ULONG tid );
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);
tid - The UniqueID of a task.
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.
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.
Be careful with the return result of this function.
void CloseDevice( struct IORequest * iORequest );
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.
iORequest - Pointer to iorequest structure.
void CloseLibrary( struct Library * library );
Closes a previously opened library. It is legal to call this function with a NULL pointer.
library - Pointer to library structure or NULL.
void ColdReboot();
This function will reboot the computer.
None.
This function does not return.
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.
void CopyMem( CONST_APTR source, APTR dest, IPTR size );
Copy some memory from one destination in memory to another using a fast copying method.
source - Pointer to source area dest - Pointer to destination size - number of bytes to copy (may be zero)
The source and destination area are not allowed to overlap.
void CopyMemQuick( CONST_APTR source, APTR dest, IPTR size );
Copy some longwords from one destination in memory to another using a fast copying method.
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.
The source and destination areas are not allowed to overlap.
APTR CreateIORequest( struct MsgPort * ioReplyPort, ULONG size );
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.
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.
Pointer to a new I/O request structure or NULL if the function failed.
struct MsgPort * CreateMsgPort();
Create a new message port. A signal will be allocated and the message port set to signal you task
Pointer to messageport structure
APTR CreatePool( ULONG requirements, IPTR puddleSize, IPTR threshSize );
Create a private pool for memory allocations.
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.
A handle for the memory pool or NULL if the pool couldn't be created
\* 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); }
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.
void Deallocate( struct MemHeader * freeList, APTR memoryBlock, IPTR byteSize );
Free block of memory associated with a given MemHandler structure.
freeList - Pointer to the MemHeader structure memoryBlock - Pointer to the memory to be freed byteSize - Size of the block
The start and end borders of the block are aligned to a multiple of sizeof(struct MemChunk) and to include the block.
void Debug( unsigned long flags );
Runs SAD - internal debuger.
flags not used. Should be 0 now.
void DeleteIORequest( APTR iorequest );
Delete an I/O request created with CreateIORequest().
iorequest - Pointer to I/O request structure or NULL.
void DeleteMsgPort( struct MsgPort * port );
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.
port - Pointer to messageport structure.
void DeletePool( APTR poolHeader );
Delete a pool including all its memory.
poolHeader - The pool allocated with CreatePool() or NULL.
void Disable();
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 is not recommended to use this function for ** ANY ** reason. It is quite possible to either crash the system, or to prevent normal activities (disk/port i/o) from occuring. Note: As taskswitching is driven by the interrupts subsystem, this function has the side effect of disabling multitasking.
Interrupts will be disabled AFTER this call returns.
No you DEFINITELY don't want to use this function.
This function preserves all registers. To prevent deadlocks calling Wait() in disabled state breaks the disable - thus interrupts may happen again.
The only architecture that you can rely on the registers being saved is on the Motorola mc68000 family.
void Dispatch();
PRIVATE function to dispatch next available task
None
None
This function was private in AmigaOS(tm) up to v3.1. There's no guarantee that it will continue to exist in other systems.
LONG DoIO( struct IORequest * iORequest );
Start an I/O request by calling the devices's BeginIO() vector. It waits until the request is complete.
iORequest - Pointer to iorequest structure.
OpenDevice() notes explain LONG return type.
void Enable();
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 is not recommended to use this function for ** ANY ** reason. It is quite possible to either crash the system, or to prevent normal activities (disk/port i/o) from occuring. Note: As taskswitching is driven by the interrupts subsystem, this function has the side effect of disabling multitasking.
None.
Interrupts will be enabled again when this call returns.
No you DEFINITATELY don't want to use this function.
This function preserves all registers. To prevent deadlocks calling Wait() in disabled state breaks the disable - thus interrupts may happen again.
The only architecture that you can rely on the registers being saved is on the Motorola mc68000 family.
void Enqueue( struct List * list, struct Node * node );
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.
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 !
The new node will be inserted before nodes with lower priority.
struct List * list; struct Node * node; node->ln_Pri = 5; // Sort the node at the correct place into the list Enqueue (list, node);
The list has to be in descending order in respect to the field ln_Pri of all nodes.
void ExitIntr();
PRIVATE architecture specific routine for exiting interrupts.
None
None
This function was private in AmigaOS(tm) up to v3.1. There's no guarantee that it will exist in other systems.
struct Node * FindName( struct List * list, CONST_STRPTR name );
Look for a node with a certain name in a list.
list - Search this list. name - This is the name to look for.
struct List * list; struct Node * node; // Look for a node with the name "Hello" node = FindName (list, "Hello");
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.
struct MsgPort * FindPort( CONST_STRPTR name );
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.
port - Pointer to NUL terminated C string.
Pointer to struct MsgPort or NULL if there is no port of that name.
struct Resident * FindResident( const UBYTE * name );
Search for a Resident module in the system resident list.
name - pointer to the name of a Resident module to find
pointer to the Resident module (struct Resident *), or null if not found.
struct SignalSemaphore * FindSemaphore( CONST_STRPTR name );
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.
name - Pointer to name.
Address of semaphore structure found or NULL.
struct Task * FindTask( CONST_STRPTR name );
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.
name - Pointer to name or NULL for current task.
Address of task structure found.
struct Task * FindTaskByPID( ULONG id );
Scan through the task lists searching for the task whose et_UniqueID field matches.
id - The task ID to match.
Address of the Task control structure that matches, or NULL otherwise.
This function is source-compatible with MorphOS.
void Forbid();
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().
None.
The multitasking state will be disabled AFTER this function returns to the caller.
No you really don't want to use this function.
This function preserves all registers. To prevent deadlocks calling Wait() in forbidden state breaks the forbid - thus taskswitches may happen again.
The only architecture that you can rely on the registers being saved is on the Motorola mc68000 family.
void FreeEntry( struct MemList * entry );
Free some memory allocated with AllocEntry().
entry - The MemList you got from AllocEntry().
void FreeMem( APTR memoryBlock, IPTR byteSize );
Give a block of memory back to the system pool.
memoryBlock - Pointer to the memory to be freed byteSize - Size of the block
void FreePooled( APTR poolHeader, APTR memory, IPTR memSize );
Free memory that was allocated out of a private memory pool by AllocPooled().
poolHeader - Handle of the memory pool memory - Pointer to the memory memSize - Size of the memory chunk
void FreeSignal( LONG signalNum );
Free a signal allocated with AllocSignal().
signalNum - Number of the signal to free or -1 to do nothing.
void FreeTaskStorageSlot();
This function will free a slot in taskstorage
slot - The slot to free.
None.
Currently no checks are performed to determine if one is the owner of the slot. This may be added in the future, so one should deallocate a slot from the same task that allocated the slot.
void FreeTrap( long trapNum );
void FreeVec( APTR memoryBlock );
Free some memory previously allocated with AllocVec().
memoryBlock - The memory to be freed. It is safe to try to free a NULL pointer.
void FreeVecPooled( APTR poolHeader, APTR memory );
Free memory that was allocated out of a private memory pool by AllocVecPooled().
poolHeader - Handle of the memory pool memory - Pointer to the memory
UWORD GetCC();
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.
None.
The CPU condition codes or ~0ul if this function has not been implemented.
This function may not be implemented on platforms other than Motorola mc680x0 processors.
struct Message * GetMsg( struct MsgPort * port );
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.
port - Pointer to messageport
Pointer to message removed from the port.
IPTR GetParentTaskStorageSlot();
Get a value for a task storage slot of parent task.
id - slot ID returned from AllocTaskStorageSlot().
Value stored by SetTaskStorageSlot() on parent task, or (IPTR)NULL if the slot was never used.
Since you are accessing value of another task, the value might be invalid/freed by the time this function returns. To be sure value is still valid, call this function under Forbid().
IPTR GetTaskStorageSlot();
Get a value for a task storage slot.
id - slot ID returned from AllocTaskStorageSlot().
Value stored by SetTaskStorageSlot(), or (IPTR)NULL if the slot was never used.
void InitCode( ULONG startClass, ULONG version );
Traverse the ResModules array and InitResident() all modules with versions greater than or equal to version, and of a class equal to startClass.
startClass - which type of module to start version - a version number
This is actually internal function. There's no sense to call it from within user software.
APTR InitResident( struct Resident * resident, BPTR segList );
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
resident - Pointer to resident structure. segList - Pointer to loaded module, 0 for resident modules.
A pointer returned from the Init() vector. Usually this is the base of the library/device/resource. NULL for failure.
AUTOINIT modules are automatically added to the correct exec list. Non AUTOINIT modules have to do all the work themselves.
void InitSemaphore( struct SignalSemaphore * sigSem );
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.
sigSem - Pointer to semaphore structure
Semaphores are shared between the tasks that use them and must therefore lie in public (or at least shared) memory.
void InitStruct( CONST_APTR initTable, APTR memory, ULONG size );
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.
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.
void Insert( struct List * list, struct Node * node, struct Node * pred );
Insert Node node after pred in list.
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()).
struct List * list; struct Node * pred, * node; // Insert Node node as second node in list pred = GetHead (list); Insert (list, node, pred);
ULONG MakeFunctions( APTR target, CONST_APTR functionArray, CONST_APTR funcDispBase );
Creates the jumptable for a shared library and flushes the processor's instruction cache. Does not checksum the library.
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.
Size of the jumptable.
struct Library * MakeLibrary( CONST_APTR funcInit, CONST_APTR structInit, ULONG_FUNC libInit, ULONG dataSize, BPTR segList );
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.
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.
The library base address or NULL.
The library base is always aligned to the maximum of sizeof(LONG) and double alignment restrictions.
APTR NewAddTask( struct Task * task, APTR initialPC, APTR finalPC, struct TagItem * tagList ); APTR NewAddTaskTags( struct Task * task, APTR initialPC, APTR finalPC, TAG tag, ... );
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.
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.
The address of the new task or NULL if the operation failed (can only happen with TF_ETASK set - currenty not implemented).
This function is private. Use MorphOS-compatible NewCreateTaskA() in your applications.
struct MemList * NewAllocEntry( struct MemList * entry, ULONG * return_flags );
Allocate a number of memory blocks through a MemList structure.
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.
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.
This function is AROS-specific.
struct Task * NewCreateTaskA( struct TagItem * tags ); struct Task * NewCreateTask( TAG tag, ... );
Create a new task.
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.
A pointer to the new task or NULL on failure.
Value of TASKTAG_FLAGS is actually ignored. There are some more tags which are currently not implemented.
void NewMinList( struct MinList * list );
Initialize a list. After that, you can use functions like AddHead(), AddTail() and Insert() on the list.
list - the list to be initialized
None.
See below.
NEWLIST() macro libamiga/NewList()
IPTR NewStackSwap( struct StackSwapStruct * sss, LONG_FUNC entry, struct StackSwapArgs * args );
Calls a function with a new stack.
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.
The value returned by your function.
This function is mostly compatible with MorphOS's NewPPCStackSwap() function.
Do not attempt to pass in a prebuilt stack - it will be erased.
ULONG ObtainQuickVector( APTR interruptCode );
void ObtainSemaphoreList( struct List * sigSem );
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.
sigSem - pointer to list full of semaphores
The entire semaphore list will be locked.
void ObtainSemaphoreShared( struct SignalSemaphore * sigSem );
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().
sigSem - Pointer to semaphore structure
This function preserves all registers.
struct Library * OldOpenLibrary( UBYTE * libName );
This is the same function as OpenLibrary(), only that it uses 0 as version number. This function is obsolete. Don't use it.
LONG OpenDevice( CONST_STRPTR devName, IPTR unitNumber, struct IORequest * iORequest, ULONG flags );
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.
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.
Error code or 0 if all went well. The same value can be found in the io_Error field.
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.
struct Library * OpenLibrary( CONST_STRPTR libName, ULONG version );
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.
libName - Pointer to the library's name. version - the library's version number.
Pointer to library structure or NULL.
APTR OpenResource( CONST_STRPTR resName );
Return a pointer to a previously installed resource addressed by name. If this name can't be found NULL is returned.
resName - Pointer to the resource's name.
Pointer to resource or NULL.
void Permit();
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().
None.
Multitasking will be re-enabled.
No you really don't want to use this function.
This function preserves all registers. To prevent deadlocks calling Wait() in forbidden state breaks the forbid - thus taskswitches may happen again.
The only architecture that you can rely on the registers being saved is on the Motorola mc68000 family.
ULONG Procure( struct SignalSemaphore * sigSem, struct SemaphoreMessage * bidMsg );
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.
sigSem - pointer to semaphore structure bidMsg - pointer to a struct SemaphoreMessage. This should lie in public or at least shared memory.
Principly none. Don't know. Just ignore it.
Locks obtained with Procure() must be released with Vacate().
void PutMsg( struct MsgPort * port, struct Message * message );
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.
port - Pointer to messageport. message - Pointer to message.
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.
RAWARG RawDoFmt( CONST_STRPTR FormatString, RAWARG DataStream, VOID_FUNC PutChProc, APTR PutChData );
printf-style formatting function with callback hook.
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.
Pointer to the rest of the DataStream.
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.
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.
PutChData cannot be modified from the callback hook on non-m68k systems.
void ReleaseSemaphore( struct SignalSemaphore * sigSem );
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().
sigSem - pointer to semaphore structure
This function preserves all registers.
void ReleaseSemaphoreList( struct List * sigSem );
This function releases all semaphores in the list at once.
sigSem - pointer to list full of semaphores
void RemDevice( struct Device * device );
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.
device - Pointer to the device structure.
struct Node * RemHead( struct List * list );
Remove the first node from a list.
list - Remove the node from this list
The node that has been removed.
struct List * list; struct Node * head; // Remove node and return it head = RemHead (list);
void RemIntServer( ULONG intNumber, struct Interrupt * interrupt );
void RemLibrary( struct Library * library );
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.
library - Pointer to the library structure.
void RemMemHandler( struct Interrupt * memHandler );
Remove some function added with AddMemHandler again.
memHandler - The same Interrupt structure you gave to AddMemHandler().
void Remove( struct Node * node );
Remove a node from a list.
node - This node to be removed.
struct Node * node; // Remove node Remove (node);
There is no need to specify the list but the node must be in a list !
void RemPort( struct MsgPort * port );
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.
port - Pointer to messageport structure.
void RemResetCallback( struct Interrupt * interrupt );
Remove reset handler previously installed using AddResetCallBack()
interrupt - A pointer to an Interrupt structure
None.
This function is compatible with AmigaOS v4.
void RemResource( APTR resource );
Removes a resource from the system resource list.
resource - Pointer to the resource.
void RemSemaphore( struct SignalSemaphore * sigSem );
Removes a semaphore from the system public semaphore list.
sigSem - Pointer to semaphore structure
Semaphores are shared between the tasks that use them and must therefore lie in public (or at least shared) memory.
struct Node * RemTail( struct List * list );
Remove the last node from a list.
list - Remove the node from this list
The node that has been removed.
struct List * list; struct Node * tail; // Remove node and return it tail = RemTail (list);
void RemTask( struct Task * task );
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.
task - Task to be removed. NULL means current task.
void ReplyMsg( struct Message * message );
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.
message - a message got with GetMsg().
void Reschedule();
Give up the CPU time to other tasks (if there are any).
None
None
This function was private in AmigaOS(tm) up to v3.1. There's no guarantee that it will continue to exist in other systems.
void RestoreTaskStorage();
This function restores the current state of the task storage slots.
id - ID returned from SaveTaskStorage() referring to the state.
None.
APTR SaveTaskStorage();
This function remembers the current state of the task storage slots. An ID will be returned with which the current state can be restored using RestoreTaskStorage(). NULL is returned when not enough memory is available.
None.
id - ID for use with RestoreTaskStorage(), or NULL.
void Schedule();
PRIVATE architecture specific routine for relinquishing CPU time
None
None
This function was private in AmigaOS(tm) up to v3.1. There's no guarantee that it will continue to exist in other systems.
void SendIO( struct IORequest * iORequest );
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.
iORequest - Pointer to iorequest structure.
ULONG SetExcept( ULONG newSignals, ULONG signalSet );
Change the mask of signals causing a task exception.
newSignals - Set of signals causing the exception. signalSet - Mask of affected signals.
Old mask of signals causing a task exception.
APTR SetFunction( struct Library * library, LONG funcOffset, APTR newFunction );
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.
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).
Old jumptable entry (pointer to the old function).
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.
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.
None.
struct Interrupt * SetIntVector( ULONG intNumber, struct Interrupt * interrupt );
ULONG SetSignal( ULONG newSignals, ULONG signalSet );
Change or read the set of signals sent to the current task.
newSignals - New values for the signals. signalSet - Mask of signals affected by 'newSignals'.
Old signal set.
ULONG SetSR( ULONG newSR, ULONG mask );
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.
newSR - The new contents of the status register. mask - Mask of bits to change.
The old contents of the status register or ~0UL if this function is not implemented.
You can read the status register by calling SetSR(0,0).
This function is of limited use.
This function may do nothing on non-mc680x0 systems.
BYTE SetTaskPri( struct Task * task, LONG priority );
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.
task - Pointer to task structure. priority - New priority of the task.
Old task priority.
BOOL SetTaskStorageSlot();
Puts a new value in a task storage slot. If necessary, the number of task storage slots will be increased.
id - slot ID returned from AllocTaskStorageSlot(). value - value to store in the slot.
success - TRUE if the value was successfully stored.
ULONG ShutdownA( ULONG action ); ULONG Shutdown( TAG tag, ... );
This function will shut down the operating system.
action - what to do: * SD_ACTION_POWEROFF - power off the machine. * SD_ACTION_COLDREBOOT - cold reboot the machine (not only AROS).
This function does not return in case of success. Otherwise it returns zero.
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.
void Signal( struct Task * task, ULONG signalSet );
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.
task - Pointer to task structure. signalSet - The set of signals to send to the task.
This function may be used from interrupts.
void StackSwap( struct StackSwapStruct * sss );
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.).
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.
The program will be running on a new stack and sss will contain the old stack. Calling StackSwap() twice consecutively will effectively do nothing.
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__
ULONG SumKickData();
void SumLibrary( struct Library * library );
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.
library - Pointer to library structure.
APTR SuperState();
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.
None.
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().
This is not a good function to use, it has limited scope, and will probably be even less useful in the future.
You can easily cause your system to cease operating normally.
IPTR Supervisor( void * userFunction );
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.
userFunction - The address of the code you want called in supervisor mode.
The code will be called.
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.
You can very easily make the system unusable with this function. In fact it is recommended that you do not use it at all.
void Switch();
PRIVATE function to force a task switch to the next runnable task
None
None
This function was private in AmigaOS(tm) up to v3.1. There's no guarantee that it will continue to exist in other systems.
ULONG TypeOfMem( APTR address );
Return type of memory at a given address or 0 if there is no memory there.
address - Address to test
The memory flags you would give to AllocMem().
void UserState( APTR sysStack );
Return to user mode after a call to SuperState().
sysStack - The return value from SuperState()
The system will be back to normal.
void Vacate( struct SignalSemaphore * sigSem, struct SemaphoreMessage * bidMsg );
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.
sigSem - Pointer to semaphore structure. bidMsg - Pointer to struct SemaphoreMessage.
STRPTR VNewRawDoFmt( CONST_STRPTR FormatString, VOID_FUNC PutChProc, APTR PutChData, va_list DataStream );
printf-style formatting function with callback hook and C-style DataStream.
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)
Final PutChData value.
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); }
ULONG Wait( ULONG signalSet );
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.
signalSet - The set of signals to wait for.
The set of active signals.
Naturally it's not allowed to wait in supervisor mode. Calling Wait() breaks an active Disable() or Forbid().
LONG WaitIO( struct IORequest * iORequest );
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.
iORequest - Pointer to iorequest structure.
Error state of I/O request.
OpenDevice() notes explain LONG return type.
struct Message * WaitPort( struct MsgPort * port );
Wait until a message arrives at the given port. If there is already a message in it this function returns immediately.
port - Pointer to messageport.
Pointer to the first message that arrived at the port. The message is _not_ removed from the port. GetMsg() does this for you.