AROSAmiga Research OS

Previous Next Top of Manual blank.gif

AROS - The Amiga Research OS


NEWS
    Old News
    Status
    Credits
Documentation
    Background
    FAQ
    CVS
    MetaMake
    Coding Style
    AROS XML
    Filesystems
    HIDD Intro
    HIDD Model
    Contents
    AutoDocs
    Random Ideas
Screenshots
Downloads
Snapshots
Links
1. The AROS Filesystem Interface
1.1 It's Completely Different
1.2 Filesystem Devices
1.3 Command Documentation
1.3.1 OpenDevice
1.3.2 CloseDevice
1.3.3 FSA_OPEN
1.3.4 FSA_CLOSE
1.3.5 FSA_READ
1.3.6 FSA_WRITE
1.3.7 FSA_SEEK



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.

1.1 It's Completely Different

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.

1.2 Filesystem Devices

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:


/* IORequest from <exec/io.h> */
struct IORequest 
{
    struct Message  io_Message;
    struct Device  *io_Device;  /* filesystem base pointer */
    struct Unit           *io_Unit;    /* file or directory handle */
    UWORD           io_Command; /* the command */
    UBYTE           io_Flags;   /* normal device flags (IOF_QUICK) */
    BYTE            io_Error;   /* error code from device functions */
};

struct IOFileSys
{
    struct IORequest IOFS;
    LONG             io_DosError; /* secondary error code (IoErr()) */
    union {}         io_Union;    /* arguments - command dependant */
};

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.

1.3 Command Documentation

1.3.1 OpenDevice

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()

1.3.2 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()

1.3.3 FSA_OPEN

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

1.3.4 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

1.3.5 FSA_READ

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

1.3.6 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

1.3.7 FSA_SEEK

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.


Previous Next Top of Manual blank.gif
minilogo.gif

Amiga® is a trademark of Amiga Inc. All other trademarks belong to their respective owners.

Copyright © AROS - The Amiga Research OS
All Rights Reserved
Comments to webmaster: digulla@aros.org
Generated: Sun Sep 2, 2001