Absolute Path

See also:

• Relative Path

Current Directory

The directory, which all file-system actions are relative to, as long as no absolute path`s are used. Every `process structure stores its current directory in the field pr_CurrentDir.

Process

See also:

• Task

Relative Path

See also:

• Absolute Path

Resident List

Screen

Standard Filehandles

Standard Input

See Standard Filehandles

Standard Output

See Standard Filehandles

Standard Error

See Standard Filehandles

Task

See also:

• Process

Window

See also:

• Screen

Screen

Pointer/Integer conversions

If you need a variable which can store a pointers as an integer, don't use ULONG but IPTR. AROS guarantees that LONG is 32bit on all systems, while IPTR is always large enough to contain a pointer. Most notable things which are affected by this: TagItem`s (the `ti_Data field is now an IPTR instead of ULONG), BOOPSI classes (eg. the return value of DoMethod()), ReadArgs(), VPrintf(), VFPrintf() and more.

64 bit variables

The type of 64 bit variables is QUAD (unsigned: UQUAD). This is for example returned by the function SMult64() of utility.library. To access the high- and loworder 32bit values of the 64bit variable, use LOW32OF64() and HIGH32OF64() which are defined in AROS/include/aros/64bit.h.

Cloning RastPorts

AROS uses an external driver to access the graphics hardware. Since the nature of this driver is unknown to AROS, it is no longer valid to clone a RastPort by simply copying it. To be compatible, there are two new functions (in AROS) or macros (on Amiga): CreateRastPort(), CloneRastPort() and FreeRastPort(). You must call CloneRastPort() to create a copy or CreateRastPort() for an empty RastPort and FreeRastPort() after you've done your work with it.

This approach produces equivalent code on the Amiga but on AROS it can slow things down a bit. If you must preserve the original state of the RastPort, it's more safe to create a clone, work on it and then dispose of it again. It can also be faster if you would have to make a lot of changes to the RastPort to create two clones and set them to the two states you need. But your code should not depend on certain gains or losses of speed due to cloned RastPorts since the behaviour of the underlying graphics system is undefined.

Tag values

The original AmigaOS doesn't use the tags below USER_TAG (have a look a at utility/tagitem.h if you don't belive me) which means, you shouldn't use tags at or near USER_TAG because then they might interfere with the OS's own tags. To solve this, AROS does use the tags below USER_TAG and the various implementators need not fear that their tags may overlap with the ones from the system. The file AROS/include/utility/tagitem.h now contains the basic offsets for the various parts of the OS. In the future, it might be possible for users to allocate ranges of tags for specific uses.

DoMethod() or the stack is all wrong

There are CPUs around which don't care that the rest of the world have stacks which grow from large to small adresses. HPPA is an example for this. While it might look neat to the engineers who did it, it breaks our code. Another thing which breaks the code are small data types (eg. WORD, UBYTE, etc), because most systems put only integers or longs and pointers on the stack. So if some Msg structure expects WORD (see intuition/gadgetclass.h), this fails on every system but the Amiga. Then there are rumours about CPUs which use 32bit numbers and 64bit pointers or the other way round. On these CPUs, SetAttrs() and all other function which pass TagLists over the stack will fail. To overcome this, we introduce this rule:

If you want to pass a structure with `DoMethod()` and `DoMethodA()` or similar functions, you must prepend `STACK` to each type, like this: `WORD` becomes `STACKWORD`, `ULONG` becomes `STACKULONG`, etc.

To solve special problems on certain CPUs, we try to get a compiler which gets it right or, if that is impossible, we write a small preprocessor which replaces the dubious code by calls to the array versions.

Include files

Due to some weird reason the include files for workbench.library are called clib/wb_protos.h, defines/wb.h, inline/wb.h, wb_pragmas.h and proto/wb.h in AmigaOS. AROS decided to replace "wb" by the library's name "workbench". We provide wrapper includes for consitency to (old) AmigaOS programs, but recommend using the new names clib/workbench_protos.h, defines/workbench.h, inline/workbench.h, workbench_pragmas.h and proto/workbench.h instead.

Registers and CPUs

AROS has put some effort in defining a way to write code which is hardware independant. To achieve this, a couple of macros have been definied.

AROS_ASMSYMNAME(n)

Use this macro to access the assembler symbol n from C.

AROS_CSYMNAME(n)

Use this macro to access the C symbol n from assembler.

AROS_CDEFNAME(n)

Use this macro to define the assembler symbol n in such a way that it can be accessed from C.

AROS_SLIB_ENTRY(n,l)

Use this macro to get the name of a function n which is part of the shared library l.

AROS_UFH#(...)

Use this macro to declare a function which needs its arguments passed in registers. "#" is the number of arguments the function expects. The parameters of the macro are the return type of the function, its name and the parameters in AROS_UFHA() macros. If the function is an assembler function, you must use the AROS_ASMSYMNAME() macro to get it's name.

AROS_UFHA(t,n,r)

Use this macro to declare a parameter for a function which is declared with the AROS_UFH*() macro. It takes three arguments: The type of the parameter, the name of the parameter and the register the parameter is expected in.

AROS_UFC#(...)

Call a function which needs its arguments in registers. Works the same way as AROS_UFH*().

AROS_LH#[I](...)

Use this macro to declare a function which is part of a shared library. "#" is the number of arguments the function expects. If the function doesn't need the library base passed, you can speed up things by appending "I" to the macros name. The parameters of the macro are the return type of the function, its name, the parameters in AROS_LHA() macros, the type of the library, the name of the variable the library base is passed in, the offset in the function table (1 is the first offset and 5 is the first offset for a user function) and the name of the library.

AROS_LHA(t,n,r)

Use this macro to declare a parameter for a function which is declared with the AROS_LH*() macro. It takes three arguments: The type of the parameter, the name of the parameter and the register the parameter is expected in.

AROS_LC#[I](...)

Call a function which is part of a shared library. Works the same way as AROS_LH*().

AROS_STACK_GROWS_DOWNWARDS

has the value 1 if it is true and 0 otherwise.

AROS_BIG_ENDIAN

has the value 1 if the machine is big endian (eg. Amiga) or little endian (eg. PCs). Endianess means the way a number is stored in memory. Amiga stores 0x11223344 as 0x11 0x22 0x33 0x44 in memory while a PC does it as 0x44 0x33 0x22 0x11.

AROS_SIZEOFULONG

The result of sizeof(ULONG).

AROS_WORDALIGN

The minimal alignment of 16bit numbers in the memory of computer (WORD and UWORD).

AROS_LONGALIGN

The minimal alignment of 32bit numbers in the memory of computer (LONG and ULONG).

AROS_PTRALIGN

The minimal alignment of pointers in the memory of computer (eg. char * or APTR).

AROS_DOUBLEALIGN

The minimal alignment of 64bit IEEE floating point numbers in the memory of computer (double).

AROS_WORSTALIGN

The worst possible alignment of any data type in the memory of computer (mostly the same as AROS_DOUBLEALIGN).

AROS_ALIGN(x)

Get the next possible address where one can put any data type. This macro will return x if any data type can be put at x. Most of the time, this macro is used like this: Get a buffer, put some data in it and then use AROS_ALIGN() to find out where the next data can be put.

AROS_SLOWSTACKTAGS

is defined, if you must use GetTagsFromStack() and FreeTagsFromStack() instead of just passing the address of the tag of the first tagitem.

AROS_SLOWSTACKMETHODS

is defined, if you must use GetMsgFromStack() and FreeMsgFromStack() instead of just passing the address of the method ID.