1. The AROS Filesystem Interface

Normally, as an application programmer, you don't have to worry about the filesystem interface -- you can do everything you want via simple calls to DOS. However you may need to know how to interface with a filesystem if you

• Need to write your own filesystem,
• Wish to asynchronous I/O,
• Are writing a console driver,
• Don't trust DOS.

Of the above the most useful of these would be doing asynchronous I/O, although it is in many cases better to use one of the publically available libraries to do this, as it will hide from you the implementation of the filesystems.

The interface to filesystems is different under AROS compared to AmigaOS in many ways

• Filesystems are exec devices not process's |MsgPort|'s. This gives two main benefits -- it is possible to do some work on the callers schedule, which for simple requests can save on two context switches; and it gives us a way to abort a request, which is an important feature for a network filesystem.
• There is no difference between locks and filehandles anymore. This avoids requiring redundant methods such as ACTION_FH_FROM_LOCK.
• No BCPL -- everything is a C data type or a string. A side effect of this is that there is no limit on string size which translates to no limit on filename size either.

Obviously this change renders the filesystem incompatible to the current AmigaOS filesystems and DOS implementation. However it should be possible to build a bridge between the filesystems if necessary.

The major API change with filesystems is that they now use the Exec Device API. You can use the normal device functions (DoIO(), AbortIO(), etc). The I/O Request structure is defined in dos/filesystems.h:

The io_DosError field is used to return the secondary error code to the caller. This is the code that is returned by the dos.library function IoErr(). The io_Error field of struct IORequest should only be used to return a simple failure/success for filesystem commands, and should have the normal effect for the device open/close commands.

The io_Union field is an union containing different structures for each of the commands. This field has a variable length depending upon the command. The fields listed in the INPUTS sections of the autodocs below refer to a specific member of this union.

NAME

OpenDevice("*.handler", 0, iofs, 0);

FUNCTION

Mount a new filesystem. The IOFileSys structure passed in iofs to the handler should contain enough information for the handler to mount the filesystem.

If there is a volume mounted in this device, it is the responsibility of the handler to add the required volume nodes to the DOS device list before returning to the caller. Note here that the DOS device list is already locked, so you do not need to lock it yourself.

The filesystem must return a handle to the device in the io_Unit pointer of the struct IOFileSys. The io_Error and io_DosError fields should be set appropriately for success or failure.

INPUT

iofs

The union field io_OpenDevice is being used. Fill it with these values:

io_DeviceName

Name of the exec device to mount the filesystem upon. This device is the underlying hardware of the device. Note that this field may not be valid for some special types of handlers (for example network filesystems or special devices AUX:, SER:).

io_Unit

Unit number for the exec device. Note this is the io_Union.io_DeviceName.io_Unit field, not io_Unit.

io_Environ

This is a pointer to the struct DosEnvec which describes this device.

RESULT

io_Device

device base pointer.

io_Unit

logical device handle.

io_Error

IOERR_OPENFAIL or 0 for no error.

io_DosError

DOS error code or 0 for no error.

SEEALSO

CloseDevice()

NAME

CloseDevice()

FUNCTION

Try and dismount a DOS device. If there are any mounted volumes in the device, the filesystem should remove them from the DOS device list. Note that the DOS device list will have already been locked by the caller, so you will not have to do this yourself.

You should not dismount the device if there are still open files or outstanding locks.

INPUT

io_Unit

logical device handle.

RESULT

The DOS device shall be dismounted if possible.

io_DosError

DOS error code or 0 for no error.

SEEALSO

OpenDevice()

NAME

FSA_OPEN

FUNCTION

Create a handle to an existing file or directory. You can use this handle to read directories or read/write files.

The filename io_Args[0] is relative to the path of the directory associated with the handle io_Unit. If io_Unit is NULL however, the filename should be taken as relative to the root directory of the device.

This command uses the io_Union.io_OPEN member.

INPUT

io_Unit

Handle to current directory.

io_Filename

relative file or directory name.

io_FileMode

mode to open with:

FMF_LOCK

lock exclusively

FMF_READ

open for reading

FMF_WRITE

open for writing

FMF_EXECUTE

open to execute

RESULT

io_Unit

Freshly created handle.

io_DosError

dos error code or 0 for success.

SEEALSO

FSA_OPEN_FILE, FSA_CLOSE

NAME

FSA_CLOSE - close an open file

FUNCTION

Close a file or directory handle. You should write out any buffered data before returning. It is the responsibility of the filesystem to free the data pointed to by io_Unit.

INPUT

io_Unit

handle to file or directory

RESULT

io_DosError

DOS error code or 0 for no error.

SEEALSO

FSA_OPEN, FSA_OPEN_FILE

NAME

FSA_READ

FUNCTION

Try and read the requested number of bytes from the filehandle. A handler will normally try and fulfill the request completely, but special handlers (such as the console) may return less than the requested number of bytes.

If you reach the end of the file, you should return the number of bytes read in the current attempt. On the next call you should return 0 for EOF. Any further attempts to read should result in a return of -1 with an error code.

This function uses the io_Union.io_READ_WRITE field.

INPUT

io_Unit

filehandle

io_Buffer

pointer to byte buffer

io_Length

number of bytes to read from the file

RESULT

The buffer io_Buffer should contain some data if it was possible to read any.

io_Length

number of bytes read

io_DosError

DOS error code or 0 for no error.

SEEALSO

FSA_WRITE

NAME

FSA_WRITE - Write to a file

FUNCTION

Try to write the requested number of bytes to the filehandle. A handler should try and fulfill the request completely, but special handlers may write less than the requested number of bytes.

If you cannot write any bytes return 0 in io_Length.

This command uses the io_Union.io_READ_WRITE member.

INPUT

io_Unit

filehandle

io_Buffer

byte buffer containing data to write

io_Length

number of bytes in buffer

RESULT

The contents of the buffer should have been written to the stream.

io_Length - The number of bytes actually written io_DosError - dos error code or 0 for success.

io_Length

number of bytes read

io_DosError

DOS error code or 0 for no error.

SEEALSO

FSA_READ

NAME

FSA_SEEK - Seek within a file

FUNCTION

This command shall change the position of the next read or write in the file. The command will also return the old position in the file.

XXX: Error condition for seeking before the start, and after the end of file.

This command uses the io_Union.io_SEEK member.

INPUT

io_Unit

filehandle

io_Offset

offset

io_SeekMode

mode

OFFSET_BEGINNING

offset is relative to the beginning of the file

OFFSET_CURRENT

offset is relative to the current position

OFFSET_END

offset is relative to the end of the file

RESULT

io_Offset

old position

io_DosError

DOS error code or 0 for no error.

NOTES

A command with io_Offset == 0, and io_SeekMode == OFFSET_CURRENT is a NOP in terms of seeking and will simply return the current file position.