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. A MultiFS filing system, where necessary, should translate file names itself. This may be necessary, for example, if it manages a filing system which, on its native machine, would normally use invalid Risc OS filename characters. For example, a DOS filing system might translate the . separatoe between the filename and extension into a /, and back again.

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_Close

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_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

You 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_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.

This 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.

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 DefectList
On entry
R0 = 25
R2 = Start of buffer
R5 = Size of buffer
R6 = Image file system' file handle of image file On exit
R0,R2,R6 preserved
R5 = number of bytes left in buffer

The defect list must be filled in by the MultiFS with its best guess at the list of defects. The list must encompass all potentially defective areas in the image, even if this means having more of the disc in the defect list than the actual defects. The list should be constructed as a sequence of start, length pairs terminated with a -1 in the start field. If the defect list overflows the given buffer then R5 should be decremented below zero by the quantity of the overflow. This enables the caller to assess the size of the defect list before obtaining it for real.

ImageEntry_Func 26 AddDefect
On entry
R0 = 26
R2 = start of defect
R3 = length of defect
R6 = Image file system's file handle of image file On exit
All registers preserved

The defect should be mapped out of the image if possible. If the image's format does not support defect mapping in any way then an error should be returned something like 'This image can not map out defects'.

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

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.