acfs-handler/--background--
PURPOSE
ACFS is the AmigaDOS handler for AmigaChrome folder volumes. It
turns DOS packets into acscsi.device path commands, so a host
folder appears as an ordinary volume with locks, file handles,
Examine()/ExNext() and Info().
The host folder is the only copy of the data. ACFS keeps no cache;
every read, write and directory scan goes to the host.
MOUNTING
A mountlist entry for DH0: looks like this (filesystems/acfs/aros/DH0):
Handler = L:ACFS
StackSize = 8192
Priority = 5
GlobVec = -1
Activate = 1
ACFS takes the unit from the DOS device name: DH0: to DH7: open
acscsi.device units 0 to 7 and BOOT: opens unit 8. Any other name
uses unit 0. The volume name comes from the label the host reports
in ACSCMD_VOLUME_INFO, or the device name when there is none.
The DOS type reported in Info() is 'ACFS' (0x41434653).
PATHS
Names are resolved relative to the lock in the packet. "Vol:x"
starts again at the root. Leading slashes are skipped; "." is
ignored; "..", backslash, ':' inside a name and control characters
are rejected with ERROR_INVALID_COMPONENT_NAME. The host matches
names without regard to case, as AmigaDOS does, but on main ACFS
compares lock paths case-sensitively, so "S" and "s" do not
conflict as locks (guest PR #8 fixes this).
LOCKS
A lock is a path, not a disk key. Shared and exclusive locks on the
same path exclude each other as usual. Renaming a directory moves
every lock and open file under it to the new path. A path that has
a lock or an open file in it cannot be deleted
(ERROR_OBJECT_IN_USE).
A volume can hold at most 64 locks and 64 open files at once;
the next one fails with ERROR_NO_FREE_STORE. Guest PR #8 removes
this limit.
ERRORS
dp_Res2 carries the DOS error. The mapping from acscsi.device
results is:
NOT_FOUND ERROR_OBJECT_NOT_FOUND
EXISTS ERROR_OBJECT_EXISTS
NOT_EMPTY ERROR_DIRECTORY_NOT_EMPTY
IN_USE ERROR_OBJECT_IN_USE
ACCESS ERROR_READ_PROTECTED
READ_ONLY ERROR_DISK_WRITE_PROTECTED
INVALID_NAME ERROR_INVALID_COMPONENT_NAME
NO_SPACE ERROR_NO_FREE_STORE
WRONG_TYPE ERROR_OBJECT_WRONG_TYPE
RANGE ERROR_SEEK_ERROR
IO, PROTOCOL,
any transport error ERROR_NO_DISK
An unknown packet type returns ERROR_ACTION_NOT_KNOWN.
BUGS
Protection bits, comments, dates and file notification are not
supported: ACTION_SET_PROTECT, ACTION_SET_COMMENT, ACTION_SET_DATE,
ACTION_ADD_NOTIFY and ACTION_EXAMINE_ALL return
ERROR_ACTION_NOT_KNOWN. FileInfoBlock dates are left zero.
ACTION_INFO always reports zero blocks used.
SEE ALSO
acscsi.device/--background--, dos/dosextens.hacfs-handler/ACTION_COPY_DIR
NAME
ACTION_COPY_DIR -- DupLock()
PACKET
dp_Arg1 BPTR lock, or 0 for the root
RESULT
dp_Res1 BPTR to a new shared lock on the same path, or 0
dp_Res2 ERROR_OBJECT_IN_USE if the lock is exclusiveacfs-handler/ACTION_COPY_DIR_FH
NAME
ACTION_COPY_DIR_FH -- DupLockFromFH()
PACKET
dp_Arg1 fh_Arg1 of an open file
RESULT
dp_Res1 BPTR to a shared lock
NOTES
On main this returns a lock on the file's directory, not on the
file. Guest PR #7 changes it to lock the file itself, as AmigaDOS
specifies.
SEE ALSO
ACTION_PARENT_FHacfs-handler/ACTION_CREATE_DIR
NAME
ACTION_CREATE_DIR -- CreateDir()
PACKET
dp_Arg1 BPTR lock the name is relative to
dp_Arg2 BSTR name
RESULT
dp_Res1 BPTR to an exclusive lock on the new directory, or 0
dp_Res2 ERROR_OBJECT_EXISTS, ...acfs-handler/ACTION_CURRENT_VOLUME
NAME
ACTION_CURRENT_VOLUME -- return the volume node
PACKET
No arguments.
RESULT
dp_Res1 BPTR to the DLT_VOLUME DosList entryacfs-handler/ACTION_DELETE_OBJECT
NAME
ACTION_DELETE_OBJECT -- DeleteFile()
PACKET
dp_Arg1 BPTR lock the name is relative to
dp_Arg2 BSTR name
RESULT
dp_Res1 DOSTRUE or DOSFALSE
dp_Res2 ERROR_OBJECT_IN_USE if a lock or open file is at or under
the path; ERROR_DIRECTORY_NOT_EMPTY; ERROR_READ_PROTECTED
for the volume rootacfs-handler/ACTION_DIE
NAME
ACTION_DIE -- shut the handler down
PACKET
No arguments.
RESULT
dp_Res1 DOSTRUE, and the handler exits and frees its volume node
DOSFALSE with ERROR_OBJECT_IN_USE while any lock or file
handle is still openacfs-handler/ACTION_DISK_INFO
NAME
ACTION_DISK_INFO -- Info() without a lock
PACKET
dp_Arg1 BPTR struct InfoData
RESULT
dp_Res1 DOSTRUE or DOSFALSE
SEE ALSO
ACTION_INFOacfs-handler/ACTION_END
NAME
ACTION_END -- Close()
PACKET
dp_Arg1 fh_Arg1
RESULT
dp_Res1 DOSTRUEacfs-handler/ACTION_EXAMINE_FH
NAME
ACTION_EXAMINE_FH -- ExamineFH()
PACKET
dp_Arg1 fh_Arg1
dp_Arg2 BPTR struct FileInfoBlock
RESULT
dp_Res1 DOSTRUE or DOSFALSEacfs-handler/ACTION_EXAMINE_NEXT
NAME
ACTION_EXAMINE_NEXT -- ExNext()
PACKET
dp_Arg1 BPTR lock on a directory
dp_Arg2 BPTR struct FileInfoBlock
RESULT
dp_Res1 DOSTRUE, or DOSFALSE with ERROR_NO_MORE_ENTRIES at the end
NOTES
On main each lock keeps an entry index and every ExNext() lists
the directory again, so entries added or removed on the host during
a scan can be skipped or repeated. Guest PR #7 remembers the last
name returned instead.acfs-handler/ACTION_EXAMINE_OBJECT
NAME
ACTION_EXAMINE_OBJECT -- Examine()
PACKET
dp_Arg1 BPTR lock, or 0 for the root
dp_Arg2 BPTR struct FileInfoBlock
RESULT
dp_Res1 DOSTRUE or DOSFALSE
NOTES
fib_DirEntryType is 2 for a directory and -3 for a file.
fib_FileName is a BCPL string. fib_NumBlocks is the size in 512-byte
blocks. Examine() also restarts ExNext() on that lock.acfs-handler/ACTION_FINDINPUT
NAME
ACTION_FINDINPUT -- Open() in any of its three modes
PACKET
dp_Arg1 BPTR struct FileHandle to fill
dp_Arg2 BPTR lock the name is relative to
dp_Arg3 BSTR name
ACTION_FINDINPUT (MODE_OLDFILE) read; file must exist
ACTION_FINDOUTPUT (MODE_NEWFILE) write; created, or emptied
ACTION_FINDUPDATE (MODE_READWRITE) read and write; file must exist
RESULT
dp_Res1 DOSTRUE, with fh_Arg1 set to the file id
dp_Res2 ERROR_OBJECT_NOT_FOUND, ERROR_OBJECT_WRONG_TYPE for a
directory, ...acfs-handler/ACTION_FLUSH
NAME
ACTION_FLUSH -- nothing to flush
PACKET
No arguments.
RESULT
dp_Res1 DOSTRUE
NOTES
Every write is already on the host when ACTION_WRITE returns.acfs-handler/ACTION_FREE_LOCK
NAME
ACTION_FREE_LOCK -- UnLock()
PACKET
dp_Arg1 BPTR lock, may be 0
RESULT
dp_Res1 DOSTRUEacfs-handler/ACTION_INFO
NAME
ACTION_INFO -- Info()
PACKET
dp_Arg1 BPTR lock
dp_Arg2 BPTR struct InfoData
RESULT
dp_Res1 DOSTRUE or DOSFALSE
NOTES
id_DiskType is 'ACFS', id_DiskState ID_VALIDATED, id_NumBlocks and
id_BytesPerBlock come from the volume information. id_NumBlocksUsed
is always 0.
SEE ALSO
ACTION_DISK_INFOacfs-handler/ACTION_IS_FILESYSTEM
NAME
ACTION_IS_FILESYSTEM -- say this handler is a filesystem
PACKET
No arguments.
RESULT
dp_Res1 DOSTRUEacfs-handler/ACTION_LOCATE_OBJECT
NAME
ACTION_LOCATE_OBJECT -- Lock()
PACKET
dp_Arg1 BPTR lock the name is relative to, or 0 for the root
dp_Arg2 BSTR name
dp_Arg3 SHARED_LOCK or EXCLUSIVE_LOCK
RESULT
dp_Res1 BPTR to a new lock, or 0
dp_Res2 ERROR_OBJECT_NOT_FOUND, ERROR_OBJECT_IN_USE, ...acfs-handler/ACTION_PARENT
NAME
ACTION_PARENT -- ParentDir()
PACKET
dp_Arg1 BPTR lock
RESULT
dp_Res1 BPTR to a shared lock on the parent, or 0 for the rootacfs-handler/ACTION_PARENT_FH
NAME
ACTION_PARENT_FH -- ParentOfFH()
PACKET
dp_Arg1 fh_Arg1 of an open file
RESULT
dp_Res1 BPTR to a shared lock, or 0
NOTES
On main this returns the parent of the file's directory. Guest
PR #7 changes it to return the directory that holds the file.acfs-handler/ACTION_READ
NAME
ACTION_READ -- Read()
PACKET
dp_Arg1 fh_Arg1
dp_Arg2 buffer
dp_Arg3 bytes wanted
RESULT
dp_Res1 bytes read, 0 at end of file, -1 on erroracfs-handler/ACTION_RENAME_OBJECT
NAME
ACTION_RENAME_OBJECT -- Rename()
PACKET
dp_Arg1 BPTR lock for the old name
dp_Arg2 BSTR old name
dp_Arg3 BPTR lock for the new name
dp_Arg4 BSTR new name
RESULT
dp_Res1 DOSTRUE or DOSFALSE
dp_Res2 ERROR_OBJECT_EXISTS if the new name is taken;
ERROR_NOT_IMPLEMENTED when moving a directory into itself
NOTES
Locks and open files under the old name follow the rename. Renaming
to the same name is a no-op that succeeds.acfs-handler/ACTION_SAME_LOCK
NAME
ACTION_SAME_LOCK -- SameLock()
PACKET
dp_Arg1 BPTR lock
dp_Arg2 BPTR lock
RESULT
dp_Res1 DOSTRUE if both locks name the same pathacfs-handler/ACTION_SEEK
NAME
ACTION_SEEK -- Seek()
PACKET
dp_Arg1 fh_Arg1
dp_Arg2 offset
dp_Arg3 OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END
RESULT
dp_Res1 the position before the seek, or -1
dp_Res2 ERROR_SEEK_ERROR for a position below 0
NOTES
Seeking past the end is allowed; a later write extends the file.acfs-handler/ACTION_SET_FILE_SIZE
NAME
ACTION_SET_FILE_SIZE -- SetFileSize()
PACKET
dp_Arg1 fh_Arg1
dp_Arg2 offset
dp_Arg3 OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END
RESULT
dp_Res1 the new size, or -1acfs-handler/ACTION_WRITE
NAME
ACTION_WRITE -- Write()
PACKET
dp_Arg1 fh_Arg1
dp_Arg2 buffer
dp_Arg3 bytes to write
RESULT
dp_Res1 bytes written, or -1 on error
