> net#arf:&.doc*.FileSwitch

FS level changes since 1.20
===========================

new bits/fields in fsinfo word

fsinfo_flushnotify      * 1 :SHL: 27    ; Tell filing system when flushing
fsinfo_fsfilereadinfonolen * 1 :SHL: 26 ; fsfile_ReadInfoNoLen supported
fsinfo_fileinfo         * 1 :SHL: 25    ; fsfunc_FileInfo supported
fsinfo_setcontexts      * 1 :SHL: 24    ; fsfunc_SetContexts supported
                                        ; ^^^Don't know if this should be doc'd

fsinfo_nfiles           * &FF :SHL: 8   ; Min number of files openable on fs
                                        ; 0 -> unlimited by fs

fsargs
------

In      r0 = fsargs_Flush
        r1 = fs handle

Gives filesystem notification of a flush to media

Only needed where filesystem does buffering in addition to FileSwitch, eg.
ADFS when doing readahead/writebehind.

Only called if fsinfo_flushnotify is set in fsinfo word and stream is buffered.


fsfile
------

In      r0 = fsfunc_ReadInfoNoLen
        r1 -> filename

Out     r0 = object type
        r2 = load addr
        r3 = exec addr
        r5 = attr

Much like fsfunc_ReadInfo, but don't require length. Useful for NetFS with
FileServers as length is not stored in directory. NB. There is no high-level
equivalent of this call.

Only called if fsinfo_fsfilereadinfonolen is set in fsinfo word, otherwise
called with fsfile_ReadInfo, and returned r4 is ignored.


fsfunc
------

This WAS present at the low-level interface in 1.20 but not documented.

In      r0 = fsfunc_CatalogObjects (10_xx)
        r1 -> dirname
        r2 -> core
        r3 = max number of entries to read
        r4 = entry number in dir to start from
        r5 = ?core

Out     as per fsfunc_ReadDirEntriesInfo, except record format is:

                ALIGN
        load    *       0               ; offsets (decimal)
        exec    *       4
        length  *       8
        attr    *       12
        type    *       16
        SIN     *       20
        date    *       24              ; 5 byte (cs since 1900) fs dependent
        name    *       29...



In      r0 = fsfunc_FileInfo (10_xx)
        r1 -> wildcarded object

Produce *FileInfo type list of object name(s) + info, as much as possible.

Only called if fsinfo_fileinfo is set in fsinfo word, otherwise called with
fsfunc_Info.



Punter level changes since 1.20
===============================

OS_File
-------

In      r0 = OSFile_MakeError (10_19)
        r1 -> filename
        r2 = object type (0,1,2)

Out     VS always: r0 -> error block, eg. "File 'xyz' not found"
                                          "'xyz' is a file"
                                          "'xyz' is a directory"

Typical use is to produce prettier errors, eg.

        MOV     r0, #OSFile_ReadInfo
        SWI     XOS_File
        BVS     flurg
        TEQ     r0, #object_file
        MOVNE   r2, r0
        MOVNE   r0, #OSFile_MakeError
        SWINE   XOS_File
        BVS     flurg


OS_GBPB
-------

In      r0 = OSGBPB_ReadDirEntriesCatInfo (10_11)
        r1 -> dirname
        r2 -> core
        r3 = max number of entries to read
        r4 = entry number in dir to start from
        r5 = ?core
        r6 -> wildcard (0 -> use '*')

Out     as per OSGBPB_ReadDirEntriesInfo, except record format is:

                ALIGN
        load    *       0               ; offsets (decimal)
        exec    *       4
        length  *       8
        attr    *       12
        type    *       16
        SIN     *       20
        date    *       24              ; 5 byte (cs since 1900) fs dependent
        name    *       29...

We wanted to write a generic catalogue/examine utility, where all this info
is needed, but never got round to doing it ...

Unlike the corresponding low-level call, this was NOT available on 1.20.


Enhancement to OSGBPB_ReadDir calls (9,10,11):

In      r6 -> wildcard pattern

Now r6 = 0 -> use '*' (Logistix had problem with this)


OS_FSControl
------------

In      r0 = FSControl_Copy
        r3 new bits allowed

util_peekdest   *       1 :SHL: 14 ; Quick peek at dest before loading src ?
util_userbuffer *       1 :SHL: 13 ; Use punter's buffer as well as apl/rma ?
util_newer      *       1 :SHL: 12 ; Copy files if newer (or binary) ?
util_structureonly *    1 :SHL: 11 ; Structure only (no files) ?
util_restamp    *       1 :SHL: 10 ; Restamp datestamped files ?
util_noattr     *       1 :SHL: 9  ; Don't copy attributes over ?

        iff util_userbuffer then r8 -> more info, first word is user bufferaddr


In      r0 = FSControl_FileTypeFromString (10_31)
        r1 -> filetype string (CtrlChar term) of form 'Obey','&FFD','4_1230'

Out     r2 = filetype or error ('Bad number' etc.)


In      r0 = FSControl_FileInfo (10_32)
        r1 -> wildcarded object

Produce *FileInfo type list of object name(s) + info, as much as possible.


In      r0 = FSControl_ReadFSName (10_33)
        r1 = fs number
        r2 -> core
        r3 = ?core

Out     VC: filesystem name in core (zero terminated)
        VS: r0 -> buffer overflow

Unknown fs numbers return empty string