This is a documentation of the changes to the SWI interface to FileSwitch made between Risc OS 2.00 and 2.05.
There have been few changes made to old SWIs. Mostly they are bug fixes and slight functionality changes necessary to support MultiFS.
Bit New Meaning if set
31 special fields are supported
30 Streams are interactive
29 Filing system supports null-length filenames
28 Call the filing system for openning whether the file exists or not
27 Inform the filing system of flushes using FSEntry_Args 255
26 x Filing system supports FSEntry_File 9 (read info, no length)
25 Filing system supports FSEntry_Func 20 (*FileInfo)
24 x Filing system supports FSEntry_Func 18 (set contexts)
23 * Filing system supports MultiFS extensions
22 * Give the filing system & and % in paths when appropriate
21 * Don't bother storing directories for this filing system
20 * Don't use fsfile_Load, but use openin, GBPB, close instead
19 * Don't use fsfile_Save, but use create, openup, GBPB, close instead
18 * Use FSEntry_Func 9 (access objects) in preference to OS_Files
17 * Extra info field is present in the filing system information block
16 * Filing system is read-only
15-8 Minimum number of files openable at once
7-0 Filing system number
When bit 17 is set (extra info present) the filing system
information block is extended with an extra information word. This
means the information block has this format:
Offset Contents
&00 filing system name
&04 Startup text
&08 open
&0c getbytes
&10 putbytes
&14 args
&18 close
&1c file
&20 information word
&24 func
&28 gbpb
&2c extra information word
If the extra information word is absent, then FileSwitch will assume
its value is 0. The meanings of the extra information word bits are
as follows:
Bit Meaning when set
0 Filing system supports FSEntry_Func 34
1 Filing system should be called to do Cat
2 Filing system should be called to do Ex
3-31 reserved for future use and should be set to 0
Bits 1 and 2 of the extra info should only be set if the filing
system provides a non-standard display for Cat and Ex respectively.
FSEntry_Func 34 (fsfunc_DirIs)
In r1 = pointer to nul-terminated directory name
r2 = which directory
r6 = pointer to special field
Out registers preserved
This call is provided so that filing systems can optimise their handling of
directory cahes. It will be made when FileSwitch has successfully changed a
directory, which one being determined by r2:0-CSD,1-PSD,2-URD,3-Lib. A
filing system should not change this directory on receiving this call
(indeed, it is envisaged that a filing system would not have these
directories stored as such), instead the filing system should use this
information to help it decide which directories to cache and which to not.
The MultiFS extensions are:
FSEntry_Func 23 CanoncaliseSpecialAndDisc
In r1 = Special field or 0 if not present
r2 = disc name or 0 if not present
r3 = memory to fill special field in or 0 if just return length
r4 = memory to fill disc name in or 0 if just return length
r5 = length of special field memory block
r6 = length of disc name memory block
Out r1 = pointer to canonical special field or 0 if not present
r2 = pointer to canonical disc name or 0 if not present
r3 = length of overflow from block or special field length
r4 = length of overflow from block or disc name length
r5 = unchanged
r6 = unchanged
Convert given special field and disc name to canonical (unique) forms. If no blocks
passed in, fill in the overflow values anyway - this gives FileSwitch a
means of finding the required storage for the values. The filled in strings
should be 0 terminated.
To explain: FileSwitch will make use of this call to convert the special
field and disc name the user supplied into a canonical (unique) form.
Typically, FileSwitch will call this to tidy up the file name given by the
user into a canonical form. There are bascially two ways in which this will
be called: to find out how much space is needed for the canonical versions
of the disc and special fields; to do the conversion. These two calls will
usually be made in close succession. For example, if the user specified a
file as NetFS#Arf:&.thing.whatsit, FileSwitch will make this call as
follows:
r1 = pointer to the string "Arf" (nul terminated)
r2 = 0
r3 = 0
r4 = 0
r5 = some value of no importance as r3 is 0
r6 = some value of no importance as r4 is 0
NetFS will return these values:
r1 = pointer to canonicalised special field (actually any non-0 value will
do!)
r2 = pointer to canonicalised disc name (as above, any non-0 value will do)
r3 = length of the canonicalised special field (excluding any terminating
nul)
r4 = length of can0nicalised disc name (excluding any terminating nul)
r5 = unchanged
r6 = unchanged
FileSwitch would be expected to now allocate memory for the strings of
length specified by NetFS in the r3 and r4 return values, then call NetFS
again as follows:
r1 = pointer to the string "Arf"
r2 = 0
r3 = pointer to a buffer of length r5 bytes
r4 = pointer to a buffer of length r6 bytes
r5 = length of buffer pointed to by r3
r6 = length of buffer pointed to by r4
NetFS now fills in the buffers, (r3,r5) with the special field, (r4,r6) with
the disc name, and returns:
r1 = r3 in (buffer filled with "49.254")
r2 = r4 in (buffer filled in with "Arf")
r3 = 0 (no overflow over the end of the buffer)
r4 = 0 (no overflow over the end of the buffer)
r5 = unchanged
r6 = unchanged
FSEntry_Func 24 ResolveWildcard
In r1 = Path to a directory
r2 = Address of block to place name, or 0 if none
r3 = wildcarded object name
r5 = size of block
r6 = Special field
Out r1 = unchanged
r2 = -1 if not found, or pointer to filled in name, or 0 if no block
passed in.
r3 = unchanged
r4 = overflow of block, 0 if no overflow, -1 if FileSwitch should
resolve this wildcard itself
r5 = unchanged
This call should find which object in the given directory matches the name
given. If the filing system can not do a more efficient job than FileSwitch
would if it were to use fsentry_func 14 and then to find which was the first
match, then it should return with r4 = -1.
FSEntry_File 10 (fsfile_ReadBlockSize)
On entry
r0 = 10
r1 = file name
r6 = special field
On exit
r2 = natural block size of the file (in bytes)
r3-r5 may be corrupted
FSEntry_Func 25 (fsfunc_DefectList)
On entry
r0 = 25
r1 = pointer to nul-terminated name of image
r2 = start of buffer in memory
r5 = buffer length
r6 = special field
On exit
r0-r6 unchanged
This entry will fill the supplied buffer with the byte offsets to the start of
the defects. The list will be terminated by a &20000000 value. It is
an error for the specified image to not be the root object in an
image (eg it is an error to map out a defect from
adfs::HardDisc4.$.fred, but not an error from mapping it out from
adfs::HardDisc4.$).
FSEntry_Func 26 (fsfunc_AddDefect)
On entry
r0 = 26
r1 = pointer to nul-terminate name of image
r2 = byte offset to start of defect
r6 = special field
On exit
r0-r2,r6 preserved
This SWI will map out the specified defect from the specified image.
It is an error for the specified image to not be the root object in
an image (eg it is an error to map out a defect from
adfs::HardDisc4.$.fred, but not an error from mapping it out from
adfs::HardDisc4.$). If the defect cannot be mapped out then an error
should be returned.
FSEntry_Func 27 (fsfunc_ReadBootOption)
On entry
r0 = 27
r1 = pointer to nul-terminated name of object on thing whose boot option is to be read
r6 = special field
On exit
r0-r1,r6 preserved
r2 = boot option (as in *Opt4,n)
FSEntry_Func 28 (fsfunc_WriteBootOption)
On entry
r0 = 28
r1 = pointer to nul-terminated name of object on thing whose boot option is to be written
r2 = new boot option
r6 = special field
On exit
r0-r2,r6 preserved
FSEntry_Func 29 (fsfunc_UsedSpaceMap)
On entry
r0 = 29
r1 = pointer to nul-terminated name of an object on the disc to have its used space map gotten
r2 = buffer for map (pre-filled with 0s)
r5 = size of buffer
r6 = special field
On exit
regs preserved
Fill in 1s in the used space map for parts of the disc which are
neither free space nor bad block areas. In other words the buffer
should end up with 1s where there are used parts of the disc. Each
bit in the buffer corresponds with a BlockSize unit of the disc.
FSEntry_Func 30 (fsfunc_ReadFreeSpace)
On entry
r0 = 30
r1 = pointer to nul-terminated name of an object on the disc to have its free space gotten
r6 = special field
On exit
r0 = free space
r1 = biggest object creatable
r2 = disc size
Does the obvious.
FSEntry_Func 31 (fsfunc_NameDisc)
On entry
r0 = 31
r1 = pointer to nul-terminated name of an object on the disc to have its name changed
r2 = new name of disc (nul-terminated)
r6 = special field
On exit
regs preserved
Does the obvious
FSEntry_Func 32 (fsfunc_StampImage)
On entry
r0 = 32
r1 = pointer to nul-terminated name of an object on the disc to be stamped
r2 = type of image stamping to take place
r6 = special field
On exit
regs preserved
This call is simplar to ImageEntry_Func 32. These are the valid
values for r2 on entry:
r2 meaning
0 stamp image on next update
1 stamp image now
To stamp an image the image's unique identification number should be updated
to a different value. This value is used to distinguish between different
discs with the same name and to determine when a given disc has been
updated. The image's unique identification number is that which should be
filled in the disc record disc id field when the disc is originally
identified. This entry's form is similar to that for the ImageEntry for
consitency's sake. The most likely use is:
* When a Backup program wishes to cause a backup of the original to be
distinguishable from the original it may use the stamp image now form.
FSEntry_Func 33 (fsfunc_ObjectAtOffset)
On entry
r0 = 33
r1 = pointer to nul-terminated name of an object on the disc of imterest
r2 = offset into disc
r3 = pointer to buffer to receive object name
r4 = buffer length
r6 = special field
On exit
r2 = kind of object found at offset:
0 if offset is free; beyond end of image; a defect
1 if offset is allocated but not free, defect or beyond image end
2 if found an object at the offset and it's the only object
3 if found an object at the offset and it may share the offset with other objects
buffer filled in with name of object (r2=2,3) or buffer contents may be corrupted.
The FS should find out the usage of the given offset within the disc.
If the offset is free, a defect or outside the disc then r2 should be
returned with the value 0. If the offset is used, but has no object name
which corresponds to it (for example the free space map, FAT tables, boot
block and the such), then a return value of 1 is appropriate. If the offset
is associated with several objects (files/directories), but cannot be said
to be associated with one only (for example, the disc may have one large
section allocated which is used by several files within one directory), then
the appropriate value to return is 3. If the given offset is associated with
only one object (such that deleting that object would definitely free the
given offset), then a return value of 2 should be used. The buffer
may be corrupted during the search and, if an object is found,
should contain the path from the disc's root to the object found.
Note that no '$.' prefix should be filled in. Note also that the first
path element should have a . prefix, so the whole path filled in would
read something like:
.a.b.c.d
and not:
a.b.c.d
FSEntry_Args 10 (fsargs_ImageStampIs)
On entry
r0 = 10
r1 = file handle
r2 = new image stamp of image
On exit
regs preserved
This FSEntry_Args call is for a MultiFS to tell the host filing
system when the Id of a given image has changed, and its new value.
If your filing system does not support the root object being a
MultiFS image then these calls should be ignored. Otherwise, for
example in the case of FileCore, these calls should be used to
maintain the internal note of a disc's Id for the purposes of
identifying the disc at a later time. These calls are for
information only and should not require further action other than
the storing of the passed-in value.
OS_FSControl 35
Register an image filing system with FileSwitch
On entry
R0 = 35
R1 = module base address
R2 = offset of image filing system information block from the module base
R3 = private word pointer
On exit
Registers preserved
This call inform FileSwitch of a new image filing system to be added to the list of those it knows about. The module containing the image filing system should make this call when it initialises. This call is very similar to OS_FSControl 12 Add a filing system, except that it refers to an image filing system.
Image filing system control block:
Image file system information word
Image file system file type
Offset of routine to open files ImageEntry_Open Offset of routine to get bytes ImageEntry_GetBytes Offset of routine to put bytes ImageEntry_PutBytes Offset of routine to control open files ImageEntry_Args Offset of routine to close files ImageEntry_CloseOffset of routine to do whole file operations ImageEntry_File Offset of routine to do various FS operations ImageEntry_Func
In the following descriptions a filename or pathname will always be relative to the root directory of the supplied image file, will never have any ^s in them, nor will it have $s, @s, %s \s or &s. When a wildcarded pathname is specified, only on the final leaf should the operation in question be applied to all items; earlier wildcarded elements in the path should use the first match. A "" pathname, when passed to the image file system, indicates, in the obvious fashion, the root directory in the image file.
Image file system information word:
Bit Meaning when set
27 Notify image filing system of a flush
All bits are reserved and should be set to 0
Image file system file type:
This word gives the file type number of files which contain images
understood by this image file system.
ImageEntry_Open:
On entry
R1 = Pointer to filename (null terminated)
R6 = Image file system handle of image file
On exit
R0 = file information word
R1 = Image file system handle for this file
R2 = buffer size for FileSwitch to use (must be a power of 2 between 64 and 1024)
R3 = file length
R4 = space allocated to file (must be a multiple of buffer size)
A handle of 0 means that no file is open. This would be the case if, for example, a memory allocation failed.
file information word:
Bit Meaning if set
31 Write permitted to this file
30 Read permitted from this file
All other bits are reserved and should be set to 0
ImageEntry_GetBytes:
On entry:
R1 = Image file system file handle of file to be read from
R2 = memory address to put data
R3 = number of bytes to read
R4 = file offset to get data from
On exit
The file specified will not be a directory, but may not have read access.
In that latter case, no read access, the read is being requested so that
FileSwitch's buffers may be filled before a write operation which the user
requested. The GetBytes request should be honoured so that when FileSwitch
writes its buffer out the correct, unmodified, data is written as well as
the modified data.
ImageEntry_PutBytes:
On entry:
R1 = Image file system handle of file to be written to
R2 = memory address to get data from
R3 = number of bytes to write
R4 = file offset to put data to
On exit
The file handle is guaranteed to not be a directory and to have write access
granted when it was opened.
ImageEntry_Args:
ImageEntry_Args 3 Write file extent
On entry:
R0 = 3
R1 = Image file system's file handle
R2 = new file extent
On exit:
This call is used to set the extent of a file prior to it being closed.
ImageEntry_Args 4 Read file allocated size
On entry:
R0 = 4
R1 = Image file system's file handle
On exit:
R2 = size allocated to file by filing system
ImageEntry_Args 6 Notify of a flush
On entry
R0 = 6
R1 = Image file system's file handle
On exit:
R2 = load address of file (or 0)
R3 = execution address of file (or 0)
This call is used to notify the filing system to flush any modified data that it is holding in buffers to its image file. The image file should subsequently be flushed to ensure the flush feeds through eventually to the medium.
ImageEntry_Args 7 Ensure file size
On entry
R0 = 7
R1 = image file system's file handle
R2 = size of file to ensure
On exit
R2 = size of file actually ensured
This call is used to ensure the file can be extended to at least the given size. The image file system need not ensure the extra space is zeroed.
ImageEntry_Args 9 Read file date stamp
On entry
R0 = 9
R1 = image file system's file handle
On exit
R2 = load address of file (or 0)
R3 = execute address of file (or 0)
This call is used to read the date/time stamp of a given file. (see PRM page
982-983 for details).
ImageEntry_Close:
On entry
R1 = Image file system's file handle
R2 = new load address for file
R3 = new execute address for file
On exit
This call is used to close a file and put a new date/time stamp on it.
ImageEntry_File:
ImageEntry_File 0 Save file
On entry
r0 = 0
r1 = pointer to filename (null terminated)
r2 = load address to associate with file
r3 = execution address to associate with file
r4 = start address in memory of data
r5 = end address in memory plus one
r6 = Image file system's handle for image file
On exit
r6 = pointer to a leafname for printing *OPT 1 info
This call works exactly as the FSEntry_File 0 in the PRM works.
ImageEntry_File 1 Write catalogue information
On entry
R0 = 1
R1 = pointer to wildcarded filename (nul terminated)
R2 = new load address for file
R3 = new execution address for file
R5 = new attributes for file
R6 = Image file system's handle for image file
On exit
Write the catalogue information. If the object is a directory and your image file system cannot write the information then return an error. If the object does not exist, don't return an error.
ImageEntry_File 5 Read catalogue information
On entry
R0 = 5
R1 = pointer to wildcarded pathname (nul terminated)
R6 = image file system's handle for image file
On exit
R0 = object type
0 not found
1 file
2 directory
R2 = load addressYou should return r0=0 if the object specified does not exist, or any of the directories along its path do not exist.
ImageEntry_File 6 Delete object
On entry
R0 = 6
R1 = pointer to filename (nul terminated)
R6 = Image file system's handle for image file
On exit
R0 = object type
R2 = load address
R3 = execute address
R4 = file length
R5 = file attributes
This call deletes an object. Don't bother transfering any data for this object. The returned values refer to the object deleted. Do not return an error if the object didn't exist.
ImageEntry_File 7 Create file
On entry
R0 = 7
R1 = pointer to filename (nul terminated)
R2 = load address
R3 = execution address
R4 = length of file
R6 = Image file system's handle for image file
On exit
This call creates a file. Create the file with the given load and execute address and file length. If a file already exists, replace it with the created file, unless the original file's access attributes forbid this, in which case an error should be returned. The new file should have the same access attributes as the old one, or some default access if the old file doesn't exist.
ImageEntry_File 8 Create directory
On entry
R0 = 8
R1 = pointer to filename (nul terminated)
R2 = load address
R3 = execute address
R6 = Image file system's handle for image file
On exit
This call creates a directory. If directories don't support load and execute addresses (which will only be of the directory type/datestamp form) then no error should be returned. If the directory already exists, try renaming it (the case of the letters might have changed), but don't return an error if it fails. If the create fails return an error.
ImageEntry_File 10 (fsfile_ReadBlockSize)
On entry
r0 = 10
r1 = file name
r6 = special field
On exit
r2 = natural block size of the file (in bytes)
ImageEntry_Func:
ImageEntry_Func 8 Rename object
On entry
R0 = 8
R1 = pointer to name of object to be renamed (nul terminated)
R2 = pointer to name of new name for object (nul terminated)
R6 = Image file system's handle for image file
This call renames an object (file OR directory) within a given image file. If, in a *rename, the two objects are on different image files, then the rename will fail.
ImageEntry_Func 14 Read directory entries
On entry
R0 = 14
R1 = Pointer to wildcarded directory name
R2 = memory address to put data
R3 = number of object names to read
R4 = offset of first item to read in directory (0 for start of directory)
R5 = buffer length
R6 = Image file system's handle for image file
On exit
R3 = number of records read
R4 = offset of next item to read in directory (-1 if end)
The leaf names of entries should be placed in the supplied buffer, as for FSEntry_Func 14.
ImageEntry_Func 15 Read directory entries and information
On entry
R0 = 15
R1 = Pointer to wildcarded directory name
R2 = memory address to put data
R3 = number of object names to read
R4 = offset of first item to read in directory (0 for start of directory)
R5 = buffer length
R6 = Image file system's handle for image file
On exit
R3 = number of records read
R4 = offset of next item to read in directory (-1 if end)
The leaf names of entries and their file information should be placed in the supplied buffer, as for FSEntry_Func 15.
ImageEntry_Func 21 Notification of new image file
On entry
R0 = 21
R1 = FileSwitch file handle of file
R2 = Buffer size for file, or 0 if not known.
This should be treated as a hint to the sector size.
On exitThis notifies an image filing system that FileSwitch would like it to handle this image file. This entry gives the image filing system a chance to set up internal structures so that data could be cached or buffered from the image. All future requests FileSwitch makes of the image file system will quote the returned image file's image file system handle when appropriate. The image should be flagged internally as 'needs a new unique identification number when updated', and when it is updated its unique identification number should be updated. Whenever this number is updated the host filing system should be informed of its new value using OSArgs_ImageStampIs - this is important, because otherwise the host filing system will lose track of which disc is which.
ImageEntry_Func 22 Notification of image file about to be closed
On entry
R0 = 22
R1 = Image file system's file handle of image file
On exit
All files will have been closed for you before this call is made. You should save any buffered data for this image file before returning, and discard any cached data.
ImageEntry_Func 25 (fsfunc_DefectList)
On entry
r0 = 25
r1 = pointer to nul-terminated name of image
r2 = start of buffer in memory
r5 = buffer length
r6 = Image file system's handle for image file
On exit
r0-r6 unchanged
This entry will fill the supplied buffer with the byte offsets to the start of
the defects. The list will be terminated by a &20000000 value. It is
an error for the specified image to not be the root object in an
image (eg it is an error to map out a defect from
adfs::HardDisc4.$.fred, but not an error from mapping it out from
adfs::HardDisc4.$).
ImageEntry_Func 26 (fsfunc_AddDefect)
On entry
r0 = 26
r1 = pointer to nul-terminate name of image
r2 = byte offset to start of defect
r6 = Image file system's handle for image file
On exit
r0-r2,r6 preserved
This SWI will map out the specified defect from the specified image.
It is an error for the specified image to not be the root object in
an image (eg it is an error to map out a defect from
adfs::HardDisc4.$.fred, but not an error from mapping it out from
adfs::HardDisc4.$). If the defect cannot be mapped out then an error
should be returned.
ImageEntry_Func 27 (fsfunc_ReadBootOption)
On entry
r0 = 27
r1 = pointer to nul-terminated name of object on thing whose boot option is to be read
r6 = Image file system's handle for image file
On exit
r0-r1,r6 preserved
r2 = boot option (as in *Opt4,n)
ImageEntry_Func 28 (fsfunc_WriteBootOption)
On entry
r0 = 28
r1 = pointer to nul-terminated name of object on thing whose boot option is to be written
r2 = new boot option
r6 = Image file system's handle for image file
On exit
r0-r2,r6 preserved
ImageEntry_Func 29 (fsfunc_UsedSpaceMap)
On entry
r0 = 29
r2 = buffer for map (pre-filled with 0s)
r5 = size of buffer
r6 = Image file system's handle for image file
On exit
regs preserved
Fill in 1s in the used space map for parts of the image which are neither free space nor bad block areas. In other words the buffer should end up with 1s where there are used parts of the disc. Each bit in the buffer corresponds with a BlockSize unit of the image.
ImageEntry_Func 30 (fsfunc_ReadFreeSpace)
On entry
r0 = 30
r6 = Image file system's handle for image file
On exit
r0 = free space
r1 = biggest object creatable
r2 = disc size
Does the obvious.
ImageEntry_Func 31 (fsfunc_NameDisc)
On entry
r0 = 31
r2 = new name of disc (nul-terminated)
r6 = Image file system's handle for image file
On exit
regs preserved
Does the obvious
ImageEntry_Func 32 (fsfunc_StampImage)
On entry
r0 = 32
r2 = type of image stamping to take place
r6 = Image file system's handle for image file
On exit
regs preserved
This entry is used for FileCore to communicate with the MultiFS for control
of and management of the disc Id of a given image. These are the valid
values for r2 on entry:
r2 meaning 0 stamp image on next update 1 stamp image nowTo stamp an image the image's unique identification number should be updated to a different value. This value is used to distinguish between different discs with the same name and to determine when a given disc has been updated. The image's unique identification number is that which should be filled in the disc record disc id field when the disc is originally identified. The kind of uses expected for these calls are:
On entry
r0 = 33
r2 = offset into image
r3 = pointer to buffer to receive object name
r4 = buffer length
r6 = Image file system's handle for image file
On exit
r2 = kind of object found at offset:
0 if offset is free; beyond end of image; a defect
1 if offset is allocated but not free, defect or beyond image end
2 if found an object at the offset and it's the only object
3 if found an object at the offset and it may share the offset with other objects
buffer filled in with name of object (r2=2,3) or buffer contents may be corrupted.
The MultiFS should find out the usage of the given offset within the image.
If the offset is free, a defect or outside the image then r2 should be
returned with the value 0. If the offset is used, but has no object name
which corresponds to it (for example the free space map, FAT tables, boot
block and the such), then a return value of 1 is appropriate. If the offset
is associated with several objects (files/directories), but cannot be said
to be associated with one only (for example, the image may have one large
section allocated which is used by several files within one directory), then
the appropriate value to return is 3. If the given offset is associated with
only one object (such that deleting that object would definitely free the
given offset), then a return value of 2 should be used. The buffer may be
corrupted during the search and, if an object is found, should contain the
path from the image's root to the object found. Note also that the first
path element should have a . prefix, so the whole path filled in would
read something like:
.a.b.c.d
and not:
a.b.c.d
OS_FSControl 36
De register an image filing system with FileSwitch.
On entry
r0 = 36
r1 = image file system file type
On exit
This call removes the given image filing system from the list of those which FileSwitch knows about.
OS_FSControl 37 (FSControl_CanonicalisePath)
On entry
r0 = 37
r1 = Pointer to path to be canonicalised
r2 = Pointer to buffer to be filled in
r3 = Pointer to system variable name of path to use, or 0 if none
r4 = Pointer to default path to use if no system variable is specified
or if that variable doesn't exist, or 0 if no path is the default
r5 = Buffer length
On exit
Buffer filled in with 0-terminated canonicalised name, and
r5 = number of spare bytes in the buffer after and including
the 0 terminator. If the buffer would have overflowed,
then this will be taken to negative the overflow, but
the overflow won't actually have happened. This
provides a machanism for finding out how much buffer
is needed. Note that a value of '0' in r5 means the buffer
overflowed by 1 byte (the \0 terminator).
This may be used as a two-pass process:
Pass 1:
In:
r0 = 37
r1 = Pointer to path
r2 = 0
r5 = 0
Out:
r5 = -(length of canonicalised path)
Pass 2:
r0 = 37
r1 = Pointer to path
r2 = Pointer to claimed buffer
r5 = size of claimed buffer
Out:
r5 should be 0, but check to make sure!
v) Given a file handle, fileswitch will return the name of the file.
OS_Args 7 (OSArgs_ReadPath)
On entry
r0 = 7
r1 = file handle
r2 = Pointer to buffer to be filled in
r5 = Buffer length
On exit
Buffer filled in with 0-terminated canonicalised name, and
r5 = number of spare bytes in the buffer after the 0 terminator.
If the buffer would have overflowed, then this will be
taken to negative the overflow, but the overflow won't
actually have happened. This provides a machanism for
finding out how much buffer is needed.
This call can be used in the same way as OS_FSControl 37.
vi) FileSwitch now processes the conversion of file info into filetype information.
OS_FSControl 38 (FSControl_InfoToFileType)
On entry
r0 = 38
r1 = a pointer to the object's name
r2 = object's load address
r3 = object's execute address
r4 = object's length
r5 = objects's attributes
r6 = object's type (file/directory)
On exit
r2 = object's type:
Special values:
-1 untyped
&1000 directory
&2000 application directory (directory whose name starts with a '!').
OS_File 20-23 (OSFile_ReadWithType, _ReadWithTypePath, _ReadWithTypePathVar
and _ReadWithTypeNoPath)
On Entry
r0 = 20, 21, 22 or 23
r1 = Pointer to name of object
On exit
r0 = object's type
r1 unchanged
r2 = Object's load address or top word of date stamp (Top three bytes 000000)
r3 = Object's execute address or bottom word of date stamp
r4 = Object's length
r5 = object's attributes
r6 = Object's type:
Special values:
-1 untyped (r2, r3 are load and execute address)
&1000 directory
&2000 application directory (directory whose name starts with a '!').
OS_GBPB 12 (OSGBPB_ReadDirEntriesFileType)
On entry
r0 = 12
r1 = pointer to directory name
r2 = start address of data in memory (word aligned)
r3 = number of names to read from directory
r4 = offset of first item to read from directory (0 for start)
r5 = buffer length
r6 = Pointer to (Wildcarded) name to match
On exit
r0-r2 unchanged
r3 = number of objects read
r4 = offset of next item to read
r5, r6 unchanged
This call is similar in function to OS_GBPB 10, except the buffer is filled in with entries like this:
Offset Contents
0 Load address or high word of date stamp (Top three bytes 000000) 4 Execute address of low word of date stamp 8 Length 12 File attributes 16 Object type 20 Object's file type (as for OS_File 20-23) 24 Object's name (null terminated)
OS_FSControl 41 (FSControl_DefectList)
On entry
r0 = 41
r1 = pointer to nul-terminated name of image
r2 = start of buffer in memory
r5 = buffer length
On exit
r0-r5 unchanged
This SWI will fill the supplied buffer with the byte offsets to the start of the defects. The list will be terminated by a &20000000 value.
OS_FSControl 42 (FSControl_AddDefect)
On entry
r0 = 42
r1 = pointer to nul-terminate name of image
r2 = byte offset to start of defect
On exit
r0-r2 preserved
This SWI will map out the specified defect from the specified image.
OS_File 24 (OSFile_ReadBlockSize)
On entry
r0 = 24
r1 = file name
On exit
r2 = natural block size of the file
OS_FSControl 46 (FSControl_UsedSpaceMap)
On entry
r0 = 46
r1 = pointer to nul-terminated name of image
r2 = start of buffer in memory
r5 = buffer length
On exit
r0-r5 preserved
The supplied buffer will be filled with 0 bits for unused blocks and 1 bits for used blocks. The buffer will be filled to its limit or the file's limit, whichever is less. The 'perfect' size of the buffer can be calculated from the file's size and its block size. For non-MultiFS files the buffer will be filled with 1s. The correspondance of the file to the buffer is 1 bit to 1 block. The least significant bit (bit 0) in a byte comes before the most significant bit.
OS_FSControl 47 (FSControl_ReadBootOption)
On entry
r0 = 47
r1 = pointer to nul-terminated name of object on thing whose boot option is to be read
On exit
r0-r1 preserved
r2 = boot option (as in *Opt4,n)
OS_FSControl 48 (FSControl_WriteBootOption)
On entry
r0 = 48
r1 = pointer to nul-terminated name of object on thing whose boot option is to be written
r2 = new boot option
On exit
r0-r2 preserved
OS_FSControl 49 (FSControl_ReadFreeSpace)
On entry
r0 = 49
r1 = pointer to nul-terminated name of object on thing whose free space is to be read
On exit
r0 = free space
r1 = biggest creatable object
r2 = disc size
Does the obvious.
OS_FSControl 50 (FSControl_NameDisc)
On entry
r0 = 50
r1 = pointer to nul-terminated name of object on disc whose name is to be changed
r2 = new name of disc
On exit
regs preserved
Does the obvious.
OS_FSControl 51 (FSControl_StampImage)
On entry
r0 = 51
r1 = pointer to nul-terminated name of object which is to be image-stamped
r2 = sub-reason:
0 stamp when updated
1 stamp now
On exit
regs preserved
This call is provided to allow communication between a handler of discs (eg FileCore) and a MultiFS which is interpreting a disc (eg DOSFS). This call is made by FileCore to DOSFS to inform it that it should update the disc's unique identification number when the disc is next updated (r2=0) or now (r2=1). Under normal circumstances a user need never make use of this call.
OS_FSControl 52 (FSControl_ObjectAtOffset)
On entry
r0 = 52
r1 = pointer to nul-terminated name of object of interest
r2 = offset into disc or image
r3 = pointer to buffer to receive object name
r4 = buffer length
On exit
r2 = kind of object found at offset:
0 if offset is free; beyond end of image; a defect
1 if offset is allocated but not free, defect or beyond image end
2 if found an object at the offset and it's the only object
3 if found an object at the offset and it may share the offset with other objects
buffer filled in with name of object (r2=2,3) or buffer contents may be corrupted.
This call can be used to find out what object uses a particular offset
within an image. The image searched is the deepest image, eg if the path
supplied was:
$.pc.amiga.atari.a.b.c
where pc is a DOS disc image, amiga was an amiga image and atari an atari
disc image, then the image searched would be:
$.pc.amiga.atari
The return values reflect what usage that the given offset within that image
has. The buffer will be filled with the full path of the found object.
OS_Args 8 (OSArgs_ImageStampIs)
On entry
r0 = 8
r1 = file handle
r2 = new image stamp
On exit
regs preserved
This call is provided to allow communication between a handler of discs (eg FileCore( and a MultiFS which is interpreting a disc (eg DOSFS). This call is made by DOSFS to tell FileCore when it has changed the disc's unique identification number and its new value. FileCore's only action would be to store the new image stamp against the record for that disc so that that disc may be identified at a later time.
OS_FSControl 53 (FSControl_SetDir)
On entry
r0 = 53
r1 = pointer to rest of path
r2 = which directory to set
r3 = filing system
r6 = pointer to special field
On exit
registers preserved
This call allows a filing system to explicitly tell FileSwitch to set the
specified directory to the given path without FileSwitch performing any form
of verification on the path provided.
r1 = pointer to rest of path
This must be provided. This is the string which is the canonical path from
the disc (if present) to the leaf which is the directory. It must not have
wildcards in it, nor may it have any GSTransable bits to it. The string must
be 0-terminated. It must have a root directory of some sort (ie $, % or &
must be present at the right place). For example *Mount on ADFS may set
the library to ":HardDisc4.$.Library" and *Logon on NetFS may set the
URD to ":Arf.&".
If r1 is 0 on entry then the releavnt directory will be put into the "Unset"
state.
r2 = which directory to set
This tells FileSwitch which of the settable directories should be set:
Value Directory
0 @ - currently selected directory 1 \ - previously selected directory 2 & - user root directory 3 % - libraryOther values are illegal.
OS_FSControl 54 (FSControl_ReadDir)
On entry
r0 = 54
r1 = pointer to buffer
r2 = which directory to read
r3 = filing system
r5 = size of buffer
On exit
r1 = 0 if directory unset, else points to start of rest of path if managed
to be placed into buffer.
r5 reduced by length total size of directory string including terminator
r6 = pointer to special field or 0 if not present
This call is the reverse of FSControl_SetDir. It is expected that this call will be used twice, the first time to get the buffer length, the second time to fill the buffer. The buffer will have the special field and the rest of the path placed into it. The values in r1 and r6 are suitable for submission to FSControl_SetDir.