Aminet 18/aminetcdnumber181997.iso/Aminet/misc/emu/AROSdev.lha/AROS/docs/html/filesystems.doc

Text File | 1996-11-18 | 10KB | 389 lines

        the AROS filesystem interface
        -----------------------------

Normally you don't have to care about the interface between DOS and
the filesystem code because everything that can be done with direct
interface methods can easily be done with simple DOS calls.
Nevertheless as soon as you want to write your own FS you will need to
know how to do it.
The AROS filesystem interface is different from the normal AmigaOS
filesystem interface in many respects:
* filesystems are exec devices not process's message ports - it's possible
  to do the work on the callers schedule. This helps save context switches
  and is a cheap and simple way to multithread the FS. Another side effect
  is that the new FS interface includes a method to abort a request (an
  important feature for network interfacing).
* There is no difference between locks and filehandles anymore. This avoids
  redundant methods like e.g ACTION_FH_FROM_LOCK.
* There are only C pointers and strings, no BCPL stuff. As as side effect
  there is no limit on the size of strings any more.
The disadvantage is that it's simply incompatible to the old one. OTOH
since you don't _have_ to use it for normal application programming this
incompatibility can be avoided easily.

AROS filesystems are like exec devices, i.e. they are used with the normal
exec.library functions for devices (DoIO(), BeginIO(), AbortIO()). The
I/O request structure is defined in dos/filesystem.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;    /* Action to do */
    UBYTE io_Flags;        /* e.g. IOF_QUICK */
    BYTE io_Error;        /* unused - replaced by the io_DosError
                   field below because the DOS error codes
                   go beyond the -128..127 range */
};

struct IOFileSys
{
    struct IORequest IOFS;
    LONG io_DosError;    /* replacement for io_Error */
    IPTR io_Args[4];    /* Parameters (see rest of this file) */
};

NAME
    OpenDevice("*.handler",0,iorequest,0)

FUNCTION
    Mount a new filesystem. The I/O request given to OpenDevice()
    contains the information needed by the FS. If there are any
    volumes in the mounted drive the FS is allowed to add the
    required volume nodes to the DOS list before returning to the
    caller, i.e. the DOS list must not be locked (the device loader
    demon will need a free DOS list anyway so this is no real
    restriction). The device node must not be handled by the
    FS - this is the responsibility of the caller. All the FS has
    to do is to return a handle to the drive in the io_Unit field.
    The io_Error field must be set to a useful value so that exec
    knows whether the filesystem was opened successfully.

INPUT
    io_Args[0]    name of the exec device to mount the filesystem on
    io_Args[1]    Unit number for the exec device
    io_Args[2]    dos environment vector

RESULT
    io_Device    device base pointer
    io_Unit        logical device handle
    io_Error    IOERR_OPENFAIL or 0
    io_DosError    dos error code or 0

NAME
    CloseDevice(iorequest)

FUNCTION
    Try to dismount dos device. If there are any unused volumes in
    the mounted drive the filesystem has to remove them from the DOS
    list, i.e. the DOS list must not be locked. The device node must
    not be handled by the FS - this is the caller's responsibility.
    If the dismount fails (e.g. if there were any locks on a mounted
    volume) the device will still be opened.

INPUT
    io_Unit        logical device handle

RESULT
    io_DosError    dos error code or 0

NAME
    FSA_OPEN

FUNCTION
    Build a handle to an already existing file or directory.
    Handles may be used to read directories and to read or write
    files.

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative file- or directoryname
    io_Args[1]    mode    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    one of the dos error codes or 0

NAME
    FSA_OPEN_FILE

FUNCTION
    Open an old file or create a new one and return a handle on it.
    Works only on files - directories will be refused.

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative filename
    io_Args[1]    mode    FMF_LOCK    - lock exclusively
                FMF_READ    - open for reading
                FMF_WRITE   - open for writing
                FMF_EXECUTE - open to execute
                FMF_CREATE  - create file if it doesn't exist
                FMF_CLEAR   - delete file before opening
                FMF_RAW     - open cooked console in raw
                          mode (and vice versa)

RESULT
    io_Unit        freshly created filehandle
    io_DosError    one of the dos error codes or 0

NAME
    FSA_READ

FUNCTION
    Try to read the requested number of bytes from the filehandle.
    Normally a handler will try to fulfill the request completely
    but special handlers such as console windows may return less
    than the requested number of bytes.

INPUT
    io_Unit        filehandle
    io_Args[0]    pointer to byte buffer
    io_Args[1]    number of bytes to read from the file

RESULT
    io_Args[1]    number of bytes read
    io_DosError    one of the dos error codes or 0

NAME
    FSA_WRITE

FUNCTION
    Try to write the requested number of bytes to the filehandle.
    Normally a handler will try to fulfill the request completely
    but special handlers may write less than the requested number
    of bytes.

INPUT
    io_Unit        filehandle
    io_Args[0]    pointer to byte buffer
    io_Args[1]    number of bytes to write to the file

RESULT
    io_Args[1]    number of bytes written
    io_DosError    one of the dos error codes or 0

NAME
    FSA_SEEK

FUNCTION
    Read and change the actual position in the file.

INPUT
    io_Unit        filehandle
    io_Args[0]    upper half of offset
    io_Args[1]    lower half of offset
    io_Args[2]    mode    OFFSET_BEGINNING - offset is relative to the
                           start 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_Args[0]    upper half of old position
    io_Args[1]    lower half of old position
    io_DosError    one of the dos error codes or 0

NAME
    FSA_CLOSE

FUNCTION
    Close a file- or directory handle.

INPUT
    io_Unit        handle to file or directory

RESULT
    io_DosError    0

NAME
    FSA_EXAMINE

FUNCTION
    Get information about the current object, i.e. name, protection
    bits, etc.

INPUT
    io_Unit        handle to file or directory
    io_Args[0]    struct ExAllData buffer to be filled
    io_Args[1]    size of the buffer in bytes
    io_Args[2]    type of information to get

RESULT
    io_DosError    one of the dos error codes or 0

NAME
    FSA_EXAMINE_ALL

FUNCTION
    Read the current directory. The bigger the buffer the more entries
    can be read at once. The last entry has a ed_Next field of NULL.
    If io_DosError is !=0 the contents of the buffer are undefined.

INPUT
    io_Unit        handle to directory
    io_Args[0]    struct ExAllData buffer to be filled
    io_Args[1]    size of the buffer in bytes
    io_Args[2]    type of information to get

RESULT
    io_DosError    one of the dos error codes or 0

NAME
    FSA_CREATE_DIR

FUNCTION
    Create a new directory lock it and return a handle to it.

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative name of the directory to create
    io_Args[1]    protection flags for the new directory

RESULT
    io_Unit        handle to new directory
    io_DosError    one of the dos error codes or 0

NAME
    FSA_DELETE_OBJECT

FUNCTION
    Delete a given file or directory. Directories must be empty
    to be deleted. Objects with an open handle on them may not
    be deleted either

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative filename

RESULT
    io_DosError    one of the dos error codes or 0

NAME
    FSA_SET_PROTECT

FUNCTION
    Set protection bits for a certain file or directory.

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative filename
    io_Args[1]    new protection bits

RESULT
    io_DosError    one of the dos error codes or 0

NAME
    FSA_SET_OWNER

FUNCTION
    Set owner and group for the file or directory.

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative filename
    io_Args[1]    new user ID
    io_Args[2]    new group ID

RESULT
    io_DosError    one of the dos error codes or 0

NAME
    FSA_SET_DATE

FUNCTION
    Set modification date of the file or directory.

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative filename
    io_Args[1]    days since 1 jan 1978
    io_Args[2]    mins since midnight
    io_Args[3]    ticks since the last full minute

RESULT
    io_DosError    one of the dos error codes or 0

NAME
    FSA_SET_COMMENT

FUNCTION
    Set a new comment for the file or directory.

INPUT
    io_Unit        handle to current directory
    io_Args[0]    relative filename
    io_Args[1]    comment or NULL

RESULT
    io_DosError    one of the dos error codes or 0

NAME
    FSA_SET_FILE_SIZE

FUNCTION
    Change the size of the file.

INPUT
    io_Unit        filehandle
    io_Args[0]    upper half of offset
    io_Args[1]    lower half of offset
    io_Args[2]    mode    OFFSET_BEGINNING - offset is relative to the
                           start 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_DosError    one of the dos error codes or 0

  FSA_FILE_MODE
    Change or read the mode of a single filehandle
    Unit *current; filehandle to change
    ULONG newmode; new mode/old mode on return
    ULONG mask;    bits affected

  FSA_MOUNT_MODE
    Change or read the mode of the filesystem
    Unit *current; filesystem to change
    ULONG newmode; new mode/old mode on return
    ULONG mask;    bits affected
    STRPTR passwd; password for MMF_LOCKED

  FSA_MAKE_HARDLINK
    Create a hard link on a file, directory or soft link
    Unit *current; current directory
    STRPTR name;   hardlink name
    Unit *target;  target handle

  FSA_MAKE_SOFTLINK
    Create a soft link to another object
    Unit *current; current directory
    STRPTR name;   softlink name
    STRPTR target; target name

  FSA_RENAME
  FSA_READ_LINK
  FSA_DISK_INFO
  FSA_SERIALIZE_DISK
  FSA_WAIT_CHAR
  FSA_INFO
  FSA_TIMER
  FSA_DISK_TYPE
  FSA_DISK_CHANGE
  FSA_SAME_LOCK
  FSA_CHANGE_SIGNAL
  FSA_FORMAT
  FSA_IS_FILESYSTEM
  FSA_EXAMINE_ALL
  FSA_EXAMINE_FH
  FSA_ADD_NOTIFY
  FSA_REMOVE_NOTIFY
  FSA_EXAMINE_ALL_END