The Basic Input/Output actions are supported by both handlers and
file systems.  In this way, the application can get a stream level
access to both devices and files.  One difference that arises between
the two is that a handler will not necessarily support an ACTION_SEEK
while it is generally expected for a file system to do so.

These actions work based on a FileHandle which is filled in by one of
the three forms of opens:

ACTION_FINDINPUT         1005    Open(..., MODE_OLDFILE)
ACTION_FINDOUTPUT        1006    Open(..., MODE_NEWFILE)
ACTION_FINDUPDATE        1004    Open(..., MODE_READWRITE)
ARG1:   BPTR    FileHandle to fill in
ARG2:   LOCK    Lock on directory that ARG3 is relative to
ARG3:   BSTR    Name of file to be opened (relative to ARG1)

RES1:   BOOL    Success/Failure (DOSTRUE/DOSFALSE)
RES2:   CODE    Failure code if RES1 is DOSFALSE

All three actions use the lock (ARG2) as a base directory location
from which to open the file.  If this lock is NULL, then the file
name (ARG3) is relative to the root of the current volume.  Because
of this, file names are not limited to a single file name but instead
can include a volume name (followed by a colon) and multiple slashes
allowing the file system to fully resolve the name.  This eliminates
the need for AmigaDOS or the application to parse names before
sending them to the file system.  Note that the lock in ARG2 must be
associated with the file system in question.  It is illegal to use a
lock from another file system.

The calling program owns the file handle (ARG1).  The program must
initialize the file handle before trying to open anything  (in the
case of a call to Open(), AmigaDOS allocates the file handle
automatically and then frees it in Close() ).  All fields must be
zero except the fh_Pos and fh_End fields which should be set to -1.
The Open() function fills in the fh_Type field with a pointer to the
MsgPort of the handler process.  Lastly, the handler must initialize
fh_Arg1 with something that allows the handler to uniquely locate the
object being opened (normally a file).  This value is implementation
specific.  This field is passed to the READ/WRITE/SEEK/ END/TRUNCATE
operations and not the file handle itself.

FINDINPUT and FINDUPDATE are similar in that they only succeed if the
file already exists.  FINDINPUT will open with a shared lock while
FINDUPDATE will open it with a shared lock but if the file doesn't
exist, FINDUPDATE will create the file.  FINDOUTPUT will always open
the file (deleting any existing one) with an exclusive lock.


ACTION_READ              'R'     Read(...)
ARG1:   ARG1    fh_Arg1 field of the opened FileHandle
ARG2:   APTR    Buffer to put data into
ARG3:   LONG    Number of bytes to read

RES1:   LONG    Number of bytes read.
       0 indicates EOF.
      -1 indicates ERROR
RES2:   CODE    Failure code if RES1 is -1

This action extracts data from the file  (or input channel) at the
current position.  If fewer bytes remain in the file than requested,
only those bytes remaining will be returned with the number of bytes
stored in RES1.  The handler indicates an error is indicated by
placing a -1 in RES1 and the error code in RES2.  If the read fails,
the current file position remains unchanged.  Note that a handler may
return a smaller number of bytes than requested, even if not at the
end of a file.  This happens with interactive type file handles which
may return one line at a time as the user hits return, for example
the console handler, CON:.


ACTION_WRITE             'W'     Write(...)
ARG1:   ARG1    fh_Arg1 field of the opened file handle
ARG2:   APTR    Buffer to write to the file handle
ARG3:   LONG    Number of bytes to write

RES1:   LONG    Number of bytes written.
RES2:   CODE    Failure code if RES1 not the same as ARG3

This action copies data into the file (or output channel) at the
current position.  The file is automatically extended if the write
passes the end of the file.  The handler indicates failure by
returning a byte count in RES1 that differs from the number of bytes
requested in ARG3.  In the case of a failure, the handler does not
update the current file position (although the file may have been
extended and some data overwritten) so that an application can safely
retry the operation.


ACTION_SEEK              1008    Seek(...)
ARG1:   ARG1    fh_Arg1 field of the opened FileHandle
ARG2:   LONG    New Position
ARG3:   LONG    Mode:   OFFSET_BEGINNING,OFFSET_END, or  OFFSET_CURRENT

RES1:   LONG    Old Position.   -1 indicates an error
RES2:   CODE    Failure code if RES1 = -1

This packet sets the current file position.  The new position (ARG2)
is relative to either the beginning of the file (OFFSET_BEGINNING),
the end of the file (OFFSET_END), or the current file position
(OFFSET_CURRENT), depending on the mode set in ARG3.  Note that ARG2
can be negative.  The handler returns the previous file position in
RES1.  Any attempt to seek past the end of the file will result in an
error and will leave the current file position in an unknown location.


ACTION_END               1007    Close(...)
ARG1:   ARG1    fh_Arg1 field of the opened FileHandle

RES1:   LONG    DOSTRUE

This packet closes an open file handle.  This function generally
returns a DOSTRUE as there is little the application can do to
recover from a file closing failure.  If an error is returned under
2.0, DOS will not deallocate the file handle.  Under 1.3, it does not
check the result.


ACTION_LOCK_RECORD       2008    LockRecord(fh,pos,len,mod,tim)
ARG1:   BPTR    FileHandle to lock record in
ARG2:   LONG    Start position (in bytes) of record in the file
ARG3:   LONG    Length (in bytes) of record to be locked
ARG4:   LONG    Mode
                 0 = Exclusive
                 1 = Immediate Exclusive (timeout is ignored)
                 2 = Shared
                 3 = Immediate Shared (timeout is ignored)
ARG5:   LONG    Timeout period in AmigaDOS ticks (0 is legal)

RES1:   BOOL    Success/Failure (DOSTRUE/DOSFALSE)
RES2:   CODE    Failure code if RES1 is DOSFALSE

This function locks an area of a file in either a sharable
(indicating read-only) or exclusive (indicating read/write) mode.
Several sharable record locks from different file handles can exist
simultaneously on a particular file area but only one file handle can
have exclusive record locks on a particular area at a time.  The
``exclusivity'' of an exclusive file lock only applies to record
locks from other file handles, not to record locks within the file
handle.  One file handle can have any number of overlapping exclusive
record locks.  In the event of overlapping lock ranges, the entire
range must be lockable before the request can succeed.  The timeout
period (ARG5) is the number of AmigaDOS ticks (1/50 second) to wait
for success before failing the operation.


ACTION_FREE_RECORD       2009    UnLockRecord(file,pos,len)
ARG1:   BPTR    FileHandle to unlock record in
ARG2:   LONG    Start position (in bytes) of record in the file
ARG3:   LONG    Length of record (in bytes) to be unlocked

RES1:   BOOL    Success/Failure (DOSTRUE/DOSFALSE)
RES2:   CODE    Failure code if RES1 is DOSFALSE

This function unlocks any previous record lock.  If the given range
does not represent one that is currently locked in the file,
ACTION_FREE_RECORD returns an error.  In the event of multiple locks
on a given area, only one lock is freed.


ACTION_SET_FILE_SIZE     1022    SetFileSize(file,off,mode)
ARG1:   BPTR    FileHandle of opened file to modify
ARG2:   LONG    New end of file location based on mode
ARG3:   LONG    Mode.  One of OFFSET_CURRENT, OFFSET_BEGIN, or OFFSET_END

RES1:   BOOL    Success/Failure (DOSTRUE/DOSFALSE)
RES2:   CODE    Failure code if RES1 is DOSFALSE

This function is used to change the physical size of an opened file.
ARG2, the new end-of-file position, is relative to either the current
file position (OFFSET_CURRENT), the beginning of the file
(OFFSET_BEGIN), or the end of the file (OFFSET_END), depending on the
mode set in ARG3.  The current file position will not change unless
the current file position is past the new end-of-file position.  In
this case, the new file position will move to the new end of the
file.  If there are other open file handles on this file,
ACTION_SET_FILE_SIZE sets the end-of-file for these alternate file
handles to either their respective current file position or to the
new end-of-file position of the file handle in ARG1, whichever makes
the file appear longer.