Reading files

FIXME

Writing and creating files

FIXME

Tasks

AROS is a multitasking operating system. This essentially means that multiple programs may be run at the same time. Every program running is called a task. But there are also tasks that are not user-programs. There are, for example, tasks handling the file-system and tasks watching the input devices. Every task gets a certain amount of time, in which it is running. After this time it's the next task's turn; the system reschedules the tasks.

Plain tasks are very limited in their capabilities. Plain tasks must not call a function of dos.library or a function that could call a function of dos.library (this includes OpenLibrary() for most cases!). Processes don't have this limitation.

#include <proto/exec.h>

struct Task *FindTask( STRPTR name );

#include <proto/exec.h>

BYTE SetTaskPri( struct Task *task, BYTE newpri );

#include <proto/exec.h>

void StackSwap( struct StackSwapStruct *sss );

Processes

A process is an expanded task. Different from a task, it can use functions of dos.library, because a process structure contains some special fields, concerning files and directories. But of course, all functions that can be used on tasks can also be used on processes.

Creating own Tasks and Processes

There are mainly two methods of creating tasks and processes: you can either call an external program (i.e. open an executable file and run the program contained in it) or you can execute a piece of code, already in memory.

Expanded Error Diagnostics

Most functions of dos.library set the secondary error-code of the process structure on error. This way the caller can determine, why a certain system-call failed. Imagine, the function Open(), which opens a named file, fails. There can be multiple reasons for this: maybe the file named doesn't exist, maybe it is read protected. To find this out, you can query the secondary error-code set by the last function by using:

#include <proto/dos.h>

LONG IoErr()

DOS-functions return one of the ERROR_ definitions from dos/dos.h. Applications can, of course, process these error-codes as well (which is useful in many cases), but often we just want to inform the user what went wrong. (Applications normally need not care if a file could not be opened because it did not exist or because it was read protected.) To output human-readable error messages, dos.library provides two functions:

#include <proto/dos.h>

LONG Fault( LONG code, STRPTR header, STRPTR buffer, LONG length );
BOOL PrintFault( LONG code, STRPTR header );

While PrintFault() simply prints an error message to the standard output, Fault() fills a supplied buffer with the message. Both functions take a code argument. This is the code to be converted into a string. You can also supply a header string, which will prefix the error message. The header may be NULL, in which case nothing is prefixed.

Fault() also required a pointer to a buffer, which is to be filled with the converted string. The length of this buffer (in bytes) is to be passed in as the last argument. The total number of characters put into the buffer is returned. You are on the safe side, if your buffer has a size of 83 character plus the size of the header.

Examples for the use of these functions can be found in later chapters, especially in the chapter about .. FIXME:: Files and Directories.

Secondary error-codes from a program are handed back to the caller. If this is a shell, the secondary error-code will be put into the field cli_Result2 of the shell structure (struct CommandLineInterface as defined in dos/dosextens.h and .. FIXME:: discussed later.

You can also set the secondary error-code yourself. This way, you can either to pass it back to another function in your program or to your caller. To set the secondary error, use:

#include <proto/dos.h>

LONG SetIoErr( LONG code );

code is the new secondary error-code and the old secondary error-code is returned.