|
www.riscos.com Technical Support: |
FileSwitch provides services common to all filing systems. It communicates with the filing systems using a defined interface; it uses this to tell the filing systems when they must do things. It also switches between the different filing systems, keeping track of the state of each of them.
See also the Introduction to filing systems.
You can add filing system modules to the system, just as you can add any other module. They have to conform to the standards for modules, set out in the Modules; they also have to meet certain other standards to function correctly with FileSwitch as a filing system.
Because FileSwitch is already doing a lot of the work for you, you will have less work to do when you add a filing system than would otherwise be the case. Full details of how to add a filing system to FileSwitch are set out in the Writing a filing system.
FileSwitch does not lay down the format in which data must be laid out on a filing system, but it does specify what the user interface should look like.
The following terms are used in the rest of this chapter:
Filename elements may be up to ten characters in length on FileCore-based filing systems (such as ADFS) and on NetFS. These characters may be digits or letters. FileSwitch makes no distinction between upper and lower case, although filing systems can do so. As a general rule, you should not use top-bit-set characters in filenames, although some filing systems (such as FileCore-based ones) support them. You may use other characters provided they do not have a special significance. Those that do are listed below:
There is a subtle difference in wildcard matching between RISC OS 2 and later versions. Under RISC OS 2, commands acting only on files try to match wildcarded specifications against files only. However, under later versions these commands try to match against all objects; the first match found may be a directory, hence causing an error. (Similarly, a wildcarded specification passed to a command acting only on directories may get matched to a file.)
You may group files together into directories; this is particularly useful for grouping together all files of a particular type. Files in the directory currently selected may be accessed without reference to the directory name. Filenames must be unique within a given directory. Directories may contain other directories, leading to a hierarchical file structure.
The root directory, $, forms the top of the hierarchy of the media which contains the CSD. Through it you can access all files on that media. $ does not have a parent directory. Trying to access its parent will just access $. Note also that files have access permissions associated with them, which may restrict whether you can actually read or write to them.
Files in directories other than the current directory may be accessed either by making the desired directory the current directory, or by prefixing the filename by an appropriate directory specification. This is a sequence of directory names starting from one of the single-character directory names listed above, or from the current directory if none is given.
Each directory name is separated by a '.' character. For example:
| $.Documents.Memos | File Memos in dir Documents in $ |
| BASIC.Games.Adventures | File Adventures in dir Games in dir @.BASIC |
| %.BCPL | File BCPL in the current library |
Files may also be accessed on filing systems other than the current one by prefixing the filename with a filing system specification. A filing system name may appear between '-' characters, or suffixed by a ':'. For example:
-net-$.SystemMesg
adfs:%.AAsm
You are strongly advised to use the latter, as the character '-' can also be used to introduce a parameter on a command line, or as part of a file name.
Special fields are used to supply more information to the filing system than you can using standard path names; for example NetFS and NetPrint use them to specify server addresses or names. They are introduced by a # character; a variety of syntaxes are possible:
net#MJHardy::disc1.$.mike
#MJHardy::disc1.$.mike
-net#MJHardy-:disc1.$.mike
-#MJHardy-:disc1.$.mike
The special fields here are all MJHardy, and give the name of the fileserver to use.
Special fields may use any character except for control characters, double quote '"', solidus '|' and space. If a special field contains a hyphen you may only use the first two syntaxes given above.
Special fields are passed to the filing system as null-terminated strings, with the '#' and trailing ':' or '-' stripped off. If no special field is specified in a pathname, the appropriate register in the FS routine is set to zero. See below for details of which calls may take special fields.
The system variable FileSwitch$SpecialField is also used to store the special field.
FileSwitch keeps track of which filing system is currently selected. If you don't explicitly tell FileSwitch which filing system to use, it will use the current selection.
FileSwitch also keeps a record of each filing system's current selections, such as its CSD, CSL, PSD and URD. (Under RISC OS 2, this is independently recorded by individual filing systems, rather than by FileSwitch.)
Some of these values are available in system variables under RISC OS 3. These are:
See also the Using FileSwitch$SpecialField with path variables.
The top 24 bits of the file attributes are filing system dependent, eg NetFS returns the file server date of creation/modification of the object (see the chapter entitled File attributes). The low byte has the following interpretation:
| Bit | Meaning if set |
|---|---|
| 0 | Object has read access for you |
| 1 | Object has write access for you |
| 2 | Owner execute only (BBC ADFS only), or |
| Private (SJ Research file servers only) | |
| 3 | Object is locked against deletion by you |
| 4 | Object has read access for others |
| 5 | Object has write access for others |
| 6 | Undefined |
| 7 | Object is locked against deletion for others |
FileCore based filing systems (such as ADFS and RamFS) ignore the settings of bits 4 and 5, but you can still set these attributes independently of bits 0, 1 and 3. This is so that you can freely move files between ADFS, RamFS and NetFS without losing information on their public read and write access.
You should clear bits 2, 6 and 7 when you create file attributes for a file. They may be used in the future for expansion, so any routines that update the attributes must not alter these bits, and any routines that read the attributes must not assume these bits are clear.
All files have (in addition to their name, length and attributes) two 32-bit fields describing them. These are set up when the file is created and have two possible meanings:
In the case of a simple machine code program these are the load and execution addresses of the program:
| Load address | &XXXLLLLL |
| Execution address | &GGGGGGGG |
When a program is *Run, it is loaded at address &XXXLLLLL and execution commences at address &GGGGGGGG. Note that the execution address must be within the program or an error is given. That is:
XXXLLLLL 
GGGGGGGG < XXXLLLLL + Length of file
Also note that if the top twelve bits of the load address are all set (ie 'XXX' is FFF), then the file is assumed to be date-stamped. This is reasonable because such a load address is outside the addressing range of the ARM processor.
In this case the top 12 bits of the load address are all set. The remaining bits hold the date/time stamp indicating when the file was created or last modified, and the file type.
The date/time stamp is a five byte unsigned number which is the number of centi-seconds since 00:00:00 on 1st Jan 1900. The lower four bytes are stored in the execution address and the most-significant byte is stored in the least-significant byte of the load address.
The remaining 12 bits in the load address are used to store information about the file type. Hence the format of the two addresses is as follows:
| Load address | &FFFtttdd
|
| Execution address | &dddddddd
|
where 'd' is part of the date and 't' is part of the type.
The file types are split into three categories:
| Value | Meaning |
|---|---|
| &E00 - &FFF | Reserved for Acorn use |
| &800 - &DFF | For allocation to software houses |
| &000 - &7FF | Free for the user |
For a list of the file types currently defined, see the Table entitled File types.
If you type:
*Show File$Type_*
you will get a list of the file types your computer currently knows about.
Some filing systems may store additional information with each file. This is dependent on the implementation of the filing system.
When a date stamped file of type xxx is *LOADed or *RUN, FileSwitch looks for the variables Alias$@LoadType_xxx or Alias$@RunType_xxx respectively. If a variable of string or macro type exists, then it is copied (after macro expansion), and the full pathname is used to find the file either on File$Path or Run$Path. Any parameters passed are also appended for *Run commands. The whole string is then passed to the operating system command line interpreter using XOS_CLI.
For example, suppose you type
*LOAD mySprites
when in the directory adfs::HardDisc.$.Sprites, and where the type of the file mySprites is &FF9. FileSwitch will issue:
*@LoadType_FF9 adfs::HardDisc.$.Sprites.mySprites
The value of the variable Alias$@LoadType_FF9 is SLoad %*0 by default, so the CLI converts the command via the alias mechanism to:
*SLoad adfs::HardDisc.$.Sprites.mySprites
Note that RISC OS 2 does not expand file names to full pathnames and so would only issue:
*@LoadType_FF9 mySprites
which is then converted to:
*SLoad mySprites
Similarly, if you typed:
*Run BasicProg p1 p2
where BasicProg is in the directory adfs::HardDisc.$.Library, and its file type is &FFB, FileSwitch would issue:
*@RunType_FFB adfs::HardDisc.$.Library.BasicProg p1 p2
The variable Alias$@LoadType_FFB is Basic -quit |"%0|" %*1 by default, so the CLI converts the command via the alias mechanism to:
*Basic -quit "adfs::HardDisc.$.Library.BasicProg" p1 p2
The filing system manager sets several of these variables up on initialisation, which you may override by setting new ones.
In the case of BASIC programs the settings are made as follows:
*Set Alias$@LoadType_FFB Basic -load |"%0|" %*1
*Set Alias$@RunType_FFB Basic -quit |"%0|" %*1
You can set up new aliases for any new types of file. For example, you could assign type &123 to files created by your own wordprocessor. The variables could then take be set up like this:
*Set Alias$@LoadType_123 WordProc %*0
*Set Alias$@RunType_123 WordProc %*0
There are two more important variables used by FileSwitch. These control exactly where a file will be looked for, according to the operation being performed on it. The variables are:
The contents of each variable should expand to a list of prefixes, separated by commas.
When FileSwitch performs a read operation (eg load a file, open a file for input or update), then the prefixes in File$Path are used in the order in which they are listed. The first object that matches is used, whether it be a file or directory.
Similarly, when FileSwitch tries to execute a file (*Run or *filename for example), the prefixes listed in Run$Path are used in order. If a matching object is a directory then it is ignored, unless it contains a !Run file. The first file, or directory.!Run file that matches is used.
Note that the search paths in these two variables are only ever used when the pathname passed to FileSwitch does not contain an explicit filing system reference. For example, *RUN file would use Run$Path, but *RUN adfs:file wouldn't.
By default, File$Path is set to the null string, and only the current directory is searched. Run$Path is set to ',%.', so the current directory is searched first, followed by the library.
You can specify filing system names in the search paths. For example, if FileSwitch can't locate a file on the ADFS you could make it look on the Econet fileserver using:
*Set File$Path ,%.,Net:Lib*.,Net:Modules.
This would look for:
@.file, %.file, Net:Lib*.file and Net:Modules.file.
If after expansion you get an illegal filename it is not searched for. So if you had set Run$Path like this:
*Set Run$Path adfs:,,net:,%.,!
then:
*Run $.mike
would search in turn for adfs:$.mike, $.mike and net:$.mike, but not for %.$.mike or !$.mike as they are illegal.
Path variables may expand to have leading and trailing spaces around elements of the path, so:
*Set Run$Path adfs:$. , net:%. , !
is perfectly legal. If you attempt to parse path variables, you must be aw‘are of this and cope with it.
Certain SWI calls also allow you to specify alternative path strings, and to perform the operation with no path look-up at all.
You can set up other path variables and use them as pseudo filing systems. For example if you typed:
*Set Basic$Path adfs:$.basic.,net:$.basic.
you could then refer to the pseudo filing system as Basic: or (less preferable) as -Basic-.
These path variables work in the same way as File$Path and Run$Path.
When using path variables you must remember that they may specify multiple objects, and hence there are clear limitations. Reading an object specified by a correctly constructed path will always work; but writing or deleting objects using a path may be undefined in behaviour, and may hence be disallowed.
FileSwitch$SpecialField is often used as part of a macro to define a path variable. For example, the default definition of Serial$Path is this macro:
devices#<FileSwitch$SpecialField>:$.Serial.
You could change this to set up default values for the serial port as follows:
devices#baud=9600,bits=8,<FileSwitch$SpecialField>:$.Serial.
Any settings passed to FileSwitch as a special field would then override the defaults in the definition of Serial$Path.
In addition to the filing systems already mentioned, the module SystemDevices provides some device-oriented 'filing systems'. These can be used in redirection specifications in * Commands, and anywhere else where byte-oriented file operations are possible. The devices provided are:
| kbd: & rawkbd: | the keyboard |
| null: | the 'null device' |
| printer: | the printer |
| vdu: & rawvdu: | the screen |
Various other modules also provide system devices:
| device: | the device filing system |
| netprint: | the network printer |
| parallel: | the parallel port |
| pipe: | the pipe filing system |
| resources: | the resource filing system |
| serial: | the serial port |
For full details, see each chapter between NetPrint and System devices.
These are the currently allocated filing system numbers:
FileSwitch can cope fully with recursive calls made to different streams - whether through the same or different entry points. For example:
If the filing systems are different then both calls to OS_BPut will work as expected. If they are the same, then it is dependent on the filing system whether it handles it. FileCore based systems, for example, do not.
You must not call the filing systems from interrupt code; FileCore based systems in particular give an error if you try to do so.
Some of the * Commands and SWI calls listed below are provided by the kernel, and some by the FileSwitch module; they are grouped together here for ease of reference.
As well as the kernel and FileSwitch, the appropriate filing system module must be present for these commands to work, as it will carry out the low-level parts of each of the calls you make.
In addition to the calls in this section, there are OS_Bytes to read/write the *Spool and *Exec file handles. See OS_Byte 199 and OS_Byte 198 respectively for details.
Some filing systems do not support all the commands that are detailed in this chapter, and you should be aware of this when writing code. In general, filing systems for handling mass-storage media will provide full support, whereas more esoteric filing systems may have omissions, mostly because a particular function is meaningless to that filing system. If you call an unsupported command, an error will be returned, and you should program to handle this.
All calls that open a file for writing when it cannot be written to (eg write-protected media, no write access, locked filing system) do not generate an error. The error is not generated until an attempt is actually made to write the file.
R1 = &12 (reason code)
R2 = filing system number (see Filing system numbers)
R1 preserved (never claim)
R2 preserved
This is an old way to start up a filing system. It must not be claimed.
Filing system reinitialise
R1 = &40 (reason code)
R1 preserved to pass on (do not claim)
This service is called when the FileSwitch module has been reinitialised (due to a *RMReInit, for example). If you are in a filing system, you should make yourself known to FileSwitch by calling OS_FSControl 12 (see OS_FSControl 12). You must not claim this call.
R1 = &68 (reason code)
R2 = pointer to canonical filename (null terminated)
R3 = number of files closed as a result of this service call (initially 0)
R1, R2 preserved
R3 = number of files closed as a result of this service call (ie incremented appropriately)
This call requests that the object specified by R2 be closed, and also any other objects that are beneath it in the directory tree. Your module need not close the file if this may potentially cause problems.
You must not claim this service call. Before passing this service call on you must increment R3 by the number of files you closed.
For example, this call might be issued by the PC Emulator to cause a DOSFS partition file to be closed by FileSwitch. This doesn't cause problems as the partition would be spontaneously reopened if needed later.
This call is not issued by RISC OS 2.
Tells you whether the end of an open file has been reached
R0 = 127
R1 = file handle
R0 preserved
R1 indicates if end of file has been reached
R2 undefined
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call tells you whether the end of an open file has been reached, by checking whether the sequential pointer is equal to the file extent. It uses OS_Args 5 to do this; you should do so too in preference to using this call, which has been kept for compatibility only. See OS_Find for details of opening a file. The values returned in R1 are as follows:
| Value | Meaning |
|---|---|
| 0 | End of file has not been reached |
| Not 0 | End of file has been reached |
ByteV
R0 = 139
R1 = option number (first *Opt argument)
R2 = option value (second *Opt argument)
R0 preserved
R1, R2 undefined
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call selects file options. It uses OS_FSControl 10 to do this. It is equivalent to *Opt, which is documented in detail on *Opt 1.
ByteV
Reads the current auto-boot flag setting, or temporarily changes it
R0 = 255
R1 = 0 or new value
R2 = &FF or 0
R0 preserved
R1 = previous value
R2 corrupted
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call reads the current auto-boot flag setting, or changes it until the next hard reset or hard break. It uses OS_FSControl 10 to do this, which you should use in preference to this obsolete call. The auto-boot flag defaults to the value configured in the Boot/NoBoot option. If NoBoot is set, then, when the machine is reset, no auto-boot action will occur (ie no attempt will be made to access the boot file on the filing system). If Boot is the configured option, then the boot file will be accessed on reset. Either way, holding down the Shift key while releasing Reset will have the opposite effect to usual.
With this OS_Byte you can read the current state. On exit, if bit 3 of R1 is clear, then the action is Boot. If it is set, then the action is NoBoot.
The effect can be changed by writing to bit 3 of the flag, but this only lasts until the next hard reset or hard break. You should preserve the other bits of the flag.
ByteV
Acts on whole files, either loading a file into memory, saving a file from memory, or reading or writing a file's attributes
R0 = reason code
Other registers depend on reason code
R0 corrupted
Other registers depend on reason code
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
OS_File acts on whole files, either loading a file into memory, saving a file from memory, or reading or writing a file's attributes. The call indirects through FileV.
The particular action of OS_File is given by the low byte of the reason code in R0 as follows:
| R0 | Action | Page |
|---|---|---|
| 0 | Saves a block of memory as a file | OS_File 0 and 10 |
| 1 | Writes catalogue information for a named object | OS_File 1, 2, 3, 4, 9, and 18 |
| 2 | Writes load address only for a named object | OS_File 1, 2, 3, 4, 9, and 18 |
| 3 | Writes execution address only for a named object | OS_File 1, 2, 3, 4, 9, and 18 |
| 4 | Writes attributes only for a named object | OS_File 1, 2, 3, 4, 9, and 18 |
| 5 | Reads catalogue information for a named object, using File$Path | OS_File 5, 13, 15 and 17 |
| 6 | Deletes a named object | OS_File 6 |
| 7 | Creates an empty file | OS_File 7 and 11 |
| 8 | Creates a directory | OS_File 8 |
| 9 | Writes date/time stamp of a named file | OS_File 1, 2, 3, 4, 9, and 18 |
| 10 | Saves a block of memory as a file, and date/time stamps it | OS_File 0 and 10 |
| 11 | Creates an empty file, and date/time stamps it | OS_File 7 and 11 |
| 12 | Loads a named file, using specified path string | OS_File 12, 14, 16 and 255 |
| 13 | Reads catalogue information for a named object, using specified path string | OS_File 5, 13, 15 and 17 |
| 14 | Loads a named file, using specified path variable | OS_File 12, 14, 16 and 255 |
| 15 | Reads catalogue information for a named object, using specified path variable | OS_File 5, 13, 15 and 17 |
| 16 | Loads a named file, using no path | OS_File 12, 14, 16 and 255 |
| 17 | Reads catalogue information for a named object, using no path | OS_File 5, 13, 15 and 17 |
| 18 | Sets file type of a named file | OS_File 1, 2, 3, 4, 9, and 18 |
| 19 | Generates an error message | OS_File 19 |
| 20 | Reads catalogue information for a named object, using File$Path | OS_File 20, 21, 22 and 23 |
| 21 | Reads catalogue information for a named object, using specified path string | OS_File 20, 21, 22 and 23 |
| 22 | Reads catalogue information for a named object, using specified path variable | OS_File 20, 21, 22 and 23 |
| 23 | Reads catalogue information for a named object, using no path | OS_File 20, 21, 22 and 23 |
| 24 | Reads the natural block size of a file | OS_File 24 |
| 255 | Loads a named file, using File$Path | OS_File 12, 14, 16 and 255 |
For details of each of these reason codes, see below. Reason codes 20 - 24 inclusive are not supported by RISC OS 2.
FileSwitch will check the leafname for wildcard characters (* and #) before some of these operations. These are the ones which have a 'destructive' effect, eg deleting a file or saving a file (which might overwrite a file which already exists). If there are wildcards in the leafname, it returns an error without calling the filing system.
Non-destructive operations, such as loading a file and reading and writing attributes may have wildcards in the leafname. However, only the first file found will be accessed by the operation. The order of the search is filing system dependent, but is typically ASCII order.
None
R0 = 0 or 10
R1 = pointer to non-wild-leaf filename
If R0 = 0
Registers preserved
These calls save a block of memory as a file, setting either its load and execution addresses (R0 = 0), or its date/time stamp and file type (R0 = 10).
An error is returned if the object is locked against deletion, or is already open, or is a directory.
See also OS_File 7 and 11; these create an empty file, ready to receive data.
Write catalogue information for a named object
R0 = 1, 2, 3, 4, 9, or 18
R1 = pointer to (wildcarded) object name
If R0 = 1 or 2
Registers preserved
These calls write catalogue information for a named object to its catalogue entry, as shown below:
If the object name contains wildcards, only the first object matching the wildcard specification is altered.
FileCore based filing systems (such as ADFS) can write a directory's attributes; NetFS may generates an error if you try to write a directory's attributes, depending on the server you are using.
Under RISC OS 2 FileCore based filing systems do not generate an error if the object doesn't exist, whereas NetFS does so. Later versions of RISC OS always generate an error in these circumstances.
Read catalogue information for a named object
R0 = 5, 13, 15 or 17
R1 = pointer to (wildcarded) object name
If R0 = 13
R0 = object type
R1 preserved
R2 = load address
R3 = execution address
R4 = object length
R5 = object attributes
(R2 - R5 corrupted if object not found)
The load address, execution address, length and object attributes from the named object's catalogue entry are read into registers R2, R3, R4 and R5. The value of R0 on entry determines what path is used to search for the object:
| R0 | Path used |
|---|---|
| 5 | File$Path system variable |
| 13 | path string pointed to by R4 |
| 15 | path variable, name of which is pointed to by R4 |
| 17 | none |
For a description of the path strings that are held in path variables, see the chapter entitled File$Path and Run$Path.
On exit, R0 contains the object type:
| R0 | Type |
|---|---|
| 0 | Not found |
| 1 | File found |
| 2 | Directory found |
| 3 | Image file found (ie both file and directory) |
If the object name contains wildcards, only the first object matching the wildcard specification is read.
R0 = 6
R1 = pointer to non-wildcarded object name
R0 = object type
R1 preserved
R2 = load address
R3 = execution address
R4 = object length
R5 = object attributes
(R2 - R5 corrupted if object not found)
The information in the named object's catalogue entry is transferred to the registers and the object is then deleted from the structure. It is not an error if the object does not exist.
An error is generated if the object is locked against deletion, or if it is a directory which is not empty, or is already open.
The version of NetFS supplied in RISC OS 2 behaves unusually in two ways:
The version supplied in RISC OS 3 does not behave like this.
R0 = 7 or 11
R1 = pointer to non-wild-leaf file name
If R0 = 7
Registers preserved
Creates an empty file, setting either its reload and execution addresses (R0 = 7), or its date/time stamp and file type (R0 = 11).
Note: No data is transferred. The file does not necessarily contain zeros; the contents may be completely random. Some security-minded systems (such as NetFS/FileStore) will deliberately overwrite any existing data in the file.
An error is returned if the object is locked against deletion, or is already open, or is a directory.
See also OS_File 0 and 10; these save a block of memory as a file.
R0 = 8
R1 = pointer to non-wild-leaf object name
R4 = number of entries (0 for default)
Registers preserved
R4 indicates a minimum suggested number of entries that the created directory should contain without having to be extended. Zero is used to set the default number of entries.
Note: ADFS and other FileCore-based filing systems ignore the number of entries parameter, as this is predetermined by the disc format.
An error is returned if the object is a file which is locked against deletion. It is not an error if it refers to a directory that already exists, in which case the operation is ignored.
R0 = 12, 14, 16 or 255
R1 = pointer to (wildcarded) object name
If bottom byte of R3 is zero
R0 = object type (bit 0 always set, since object is a file)
R1 preserved
R2 = load address
R3 = execution address
R4 = file length
R5 = file attributes
These calls load a named file into memory. The value of R0 on entry determines what path is used to search for the file:
| R0 | Path used |
|---|---|
| 12 | path string pointed to by R4 |
| 14 | path variable, name of which is pointed to by R4 |
| 16 | none |
| 255 | File$Path system variable |
For a description of the path strings that are held in path variables, see the chapter entitled File$Path and Run$Path.
If the object name contains wildcards, only the first object matching the wildcard specification is loaded.
You must set the bottom byte of R3 to zero for a file that is date-stamped, and supply a load address in R2.
An error is generated if the object does not exist, or is a directory, or does not have read access, or it is a date-stamped file for which a load address was not correctly specified.
R0 = 19
R1 = pointer to object name to report error for
R2 = object type (0, 1, 2 or &100)
R0 = pointer to error block
V flag set
This call is used to generate a friendlier error message for the specified object, such as:
| "File 'xyz' not found" | r2 = 0 |
| "'xyz' is a file" | r2 = 1 |
| "'xyz' is a directory" | r2 = 2 or 3 |
| "Directory 'xyz' not found" | r2 = &100 |
An example of its use would be:
MOV r0, #OSFile_ReadInfo SWI XOS_File BVS error TEQ r0, #object_file MOVNE r2, r0 MOVNE r0, #OSFile_MakeError ; return error if not a file SWINE XOS_File BVS error
R2 may only have the values given above; for other values, the call returns with all registers preserved and V set (ie no error is generated). RISC OS 3.00 does not support R2 = 3, although it can return an object type of 3 (an image file); you should be cautious in passing results from other calls directly to this call.
Read catalogue information for a named object
R0 = 20, 21, 22 or 23
R1 = pointer to (wildcarded) object name
If R0 = 21
R0 = object type
R1 preserved
R2 = load address, or high byte of date stamp (top three bytes of R2 are &000000)
R3 = execution address, or low word of date stamp
R4 = object length
R5 = object attributes
R6 = object filetype (bits 0 - 11)
| Special values: | |
| -1 | untyped (R2, R3 are load and execution address), or not found (R0 is 0) |
| &1000 | directory |
| &2000 | application directory (directory whose name starts with a '!') |
This call reads the load and execution address (or date stamp), length, object attributes and filetype from the named object's catalogue entry into registers R2 - R6. The value of R0 on entry determines what path is used to search for the object:
| R0 | Path used |
|---|---|
| 20 | File$Path system variable |
| 21 | path string pointed to by R4 |
| 22 | path variable, name of which is pointed to by R4 |
| 23 | none |
For a description of the path strings that are held in path variables, see the chapter entitled File$Path and Run$Path.
On exit, R0 contains the object type:
| R0 | Type |
|---|---|
| 0 | Not found |
| 1 | File found |
| 2 | Directory found |
| 3 | Image file found (ie both file and directory) |
If the object name contains wildcards, only the first object matching the wildcard specification is read.
These calls are not available in RISC OS 2.
R0 = 24
R1 = pointer to file name
R2 = natural block size of the file in bytes
This call reads the natural block size of a file in bytes, returning it in R2. This is the same as the granularity of file allocation. For an example see the chapter entitled Allocation bytes, which gives a description of the granularity of FileCore based filing systems.
This call is not available in RISC OS 2.
Reads or writes an open file's arguments, or returns the filing system type in use
R0 = reason code
R1 = file handle, or 0
R2 = attribute to write, or not used
R0 = filing system number (see Filing system numbers), or preserved
R1 preserved
R2 = attribute that was read, or preserved
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
This call indirects through ArgsV. The particular action of OS_Args is specified by R0 as follows:
| R0 | Action | Page |
|---|---|---|
| 0 | Read pointer/FS number | OS_Args 0 |
| 1 | Write pointer | OS_Args 1 |
| 2 | Read extent | OS_Args 2 |
| 3 | Write Extent | OS_Args 3 |
| 4 | Read allocated size | OS_Args 4 |
| 5 | Read EOF status | OS_Args 5 |
| 6 | Reserve space | OS_Args 6 |
| 7 | Get canonicalised name | OS_Args 7 |
| 8 | Inform of changed image stamp | OS_Args 8 |
| 254 | Read information on file handle | OS_Args 254 |
| 255 | Ensure file/files | OS_Args 255 |
Reason codes 7 and 8 are not available under RISC OS 2.
None
ArgsV
Reads the temporary filing system number, or a file's sequential file pointer
R0 = 0
R1 = 0 or file handle
R0 = temporary filing system number (if R1 = 0 on entry), or preserved
R1 preserved
R2 = sequential file pointer (if R1 ![[NOT EQUAL]](../symbols/entities/8800.png)
0 on entry), or preserved
This call reads the temporary filing system number (if R1 = 0 on entry), or a file's sequential file pointer (if R1 0 ON ENTRY_ IN WHICH CASE IT IS TREATED AS A FILE HANDLE). FOR A LIST OF FILING SYSTEM NUMBERS_ SEE Filing system numbers.
This call indirects through ArgsV.
R0 = 1
R1 = file handle
R2 = new sequential file pointer
R0 - R2 preserved
This call writes an open file's sequential file pointer.
If the new sequential pointer is greater than the current extent, then more space is reserved for the file; this is filled with zeros. Writing the sequential pointer clears the file's EOF-error-on-next-read flag.
This call indirects through ArgsV.
R0 = 2
R1 = file handle
R0, R1 preserved
R2 = extent of file
This call reads an open file's extent. It indirects through ArgsV.
R0 = 3
R1 = file handle
R2 = new extent
R0 - R2 preserved
This call writes an open file's extent.
If the new extent is greater than the current extent, then more space is reserved for the file; this is filled with zeros. If the new extent is less than the current sequential pointer, then the sequential pointer is set back to the new extent. Writing the extent clears the file's EOF-error-on-next-read flag.
This call indirects through ArgsV.
R0 = 4
R1 = file handle
R0, R1 preserved
R2 = allocated size of file
This call reads an open file's allocated size.
The size allocated to a file will be at least as big as the current file extent; in many cases it will be larger. This call determines how many more bytes can be written to the file before the filing system has to be called to extend it. This happens automatically.
This call indirects through ArgsV.
R0 = 5
R1 = file handle
R0, R1 preserved
R2 = 0 if not EOF, else at EOF
This call reads an open file's end-of-file (EOF) status.
If the sequential pointer is equal to the extent of the given file, then an end-of-file indication is given, with R2 set to non-zero on exit. Otherwise R2 is set to zero on exit.
This call indirects through ArgsV.
R0 = 6
R1 = file handle
R2 = size to ensure
R0, R1 preserved
R2 = bytes reserved for file
This call ensures an open file's size.
The filing system is instructed to ensure that the size allocated for the given file is at least that requested. Note that this space thus allocated is not yet part of the file, so the extent is unaltered, and no data is written. R2 on exit indicates how much space the filing system actually allocated.
This call indirects through ArgsV.
R0 = 7
R1 = file handle
R2 = pointer to buffer to contain null terminated canonicalised name
R5 = size of buffer
R5 = number of spare bytes in the buffer including the null terminator, ie:
R5  1 
| there are (R5 - 1) completely unused bytes in the buffer; so R5 = 1 there are 0 unused bytes in the buffer, and therefore the terminator just fitted
|
| R5 0
| there are (1 - R5) too many bytes to fit in the buffer, which has consequently not been filled in; so R5 = 0 there is 1 byte too many - the terminator - to fit in the buffer
|
This call takes a file handle and returns its canonicalised name. This may be used as a two-pass process:
On entry, set R1 to the file handle, and R2 and R5 (the pointer to, and size of, the buffer) to zero. On exit, R5 = -(length of canonicalised name)
Claim a buffer of the right size (1-R5, not just -R5, as a space is needed for the terminator). On entry, ensure that R1 still contains the file handle, that R2 is set to point to the buffer, and R5 contains the length of the buffer. On exit the buffer should be filled in, and R5 should be 1; but check to make sure.
This call indirects through ArgsV.
It is not available in RISC OS 2.
Used by an image filing system to inform of a change to an image stamp
R0 = 8
R1 = file handle
R2 = new image stamp
R0 - R2 preserved
This call is made by an image filing system (eg DOSFS) when it has changed a disc's image stamp (a unique identification number). It does so to inform a handler of discs (eg FileCore) of the change, and to pass it the new image stamp. FileSwitch passes the information on to the disc handler, which typically just stores the new image stamp in that disc's record, so that the disc may be identified at a later time.
This call indirects through ArgsV.
It is not available in RISC OS 2.
Reads information on a file handle
R0 = 254
R1 = file handle (not necessarily allocated)
R0 = stream status word
R1 preserved
R2 = filing system information word
This call returns information on a file handle, which need not necessarily be allocated.
The stream status word is returned in R0, the bits of which have the following meaning:
If bit 11 is set then no other bits in the stream status word have any significance, and the value of the filing system information word returned in R2 is undefined.
Any bits not in the above table are undefined, but you must not presume that they are zero.
Bit 12 shows when the stream is critical - in other words, when FileSwitch has made a call to a filing system to handle an open file, and the filing system has not yet returned. This is used to protect against accidental recursion on the same file handle only.
Bit 10 shows when the stream is unbuffered; an unbuffered stream is one for which FileSwitch provides no buffering.
Bit 14 shows when an image file is busy; that is, when it is in the process of being opened by FileSwitch, but is not yet ready for use.
For a full definition of the filing system information word returned in R2, see the chapter entitled Filing system information word.
This call indirects through ArgsV.
Ensure data has been written to a file, or all files on the temporary filing system
R0 = 255
R1 = file handle, or 0 to ensure all files on the temporary filing system
R0 - R2 preserved
This call ensures that any buffered data has been written to either all files open on the temporary filing system (R1 = 0), or to the specified file (R1 0, in which case it is treated as a file handle).
This call indirects through ArgsV.
R1 = file handle
R0 = byte read if C clear, undefined if C set
R1 preserved
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
OS_BGet returns the byte at the current sequential file pointer position. The call indirects through BGetV.
If the sequential pointer is equal to the file extent (ie trying to read at end-of-file) then the EOF-error-on-next-read flag is set, and the call returns with the carry flag set, R0 being undefined. If the EOF-error-on-next-read flag is set on entry, then an End of file error is given. Otherwise, the sequential file pointer is incremented and the call returns with the carry flag clear.
This mechanism allows one attempt to read past the end of the file before an error is generated. Note that various other calls (such as OS_BPut) clear the EOF-error-on-next-read flag.
An error is generated if the file handle is invalid; also if the file does not have read access.
BGetV
R0 = byte to be written
R1 = file handle
Registers preserved
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
OS_BPut writes the byte given in R0 to the specified file at the current sequential file pointer. The sequential pointer is then incremented, and the EOF-error-on-next-read flag is cleared. The call indirects through BPutV.
An error is generated if the file handle is invalid; also if the file is a directory, or is locked against deletion, or does not have write access.
BPutV
R0 = reason code
Other registers depend on reason code
R0 preserved
Other registers depend on reason code
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call reads or writes a group of bytes from or to an open file. It indirects through GBPBV.
The particular action of OS_GBPB is given by the reason code in R0 as follows:
| R0 | Action | Page |
|---|---|---|
| 1 | Writes bytes to an open file using a specified file pointer | OS_GBPB 1 and 2 |
| 2 | Writes bytes to an open file using the current file pointer | OS_GBPB 1 and 2 |
| 3 | Reads bytes from an open file using a specified file pointer | OS_GBPB 3 and 4 |
| 4 | Reads bytes from an open file using the current file pointer | OS_GBPB 3 and 4 |
| 5 | Reads name and boot (*Opt 4) option of disc | OS_GBPB 5, 6 and 7 |
| 6 | Reads current directory name and privilege byte | OS_GBPB 5, 6 and 7 |
| 7 | Reads library directory name and privilege byte | OS_GBPB 5, 6 and 7 |
| 8 | Reads entries from the current directory | OS_GBPB 8 |
| 9 | Reads entries from a specified directory | OS_GBPB 9, 10, 11 and 12 |
| 10 | Reads entries and file information from a directory | OS_GBPB 9, 10, 11 and 12 |
| 11 | Reads entries and full file information from a directory | OS_GBPB 9, 10, 11 and 12 |
| 12 | Reads entries and file type information from a directory | OS_GBPB 9, 10, 11 and 12 |
Reason code 12 is not available under RISC OS 2.
All OS_GBPB calls either complete successfully, or return an error; they do not partially transfer the group of bytes.
Write bytes to an open file
R0 = 1 or 2
R1 = file handle
R2 = start address of buffer in memory
R3 = number of bytes to write
If R0 = 1
R0, R1 preserved
R2 = address of byte after the last one transferred from buffer
R3 = 0 (number of bytes not transferred)
R4 = initial file pointer + number of bytes transferred
C flag is cleared
Data is transferred from memory to the file at either the specified file pointer (R0 = 1) or the current one (R0 = 2). If the specified pointer is beyond the end of the file, then the file is filled with zeros between the current file extent and the specified pointer before the bytes are transferred.
The memory pointer is incremented for each byte written, and the final value is returned in R2. R3 is decremented for each byte written, and is returned as zero. The sequential pointer of the file is incremented for each byte written, and the final value is returned in R4.
The EOF-error-on-next-read flag is cleared.
An error is generated if the file handle is invalid; also if the file is a directory, or is locked against deletion, or does not have write access.
R0 = 3 or 4
R1 = file handle
R2 = start address of buffer in memory
R3 = number of bytes to read
If R0 = 3
R0, R1 preserved
R2 = address of byte after the last one transferred to buffer
R3 = number of bytes not transferred
R4 = initial file pointer + number of bytes transferred
C flag is clear if R3 = 0, else it is set
Data is transferred from the given file to memory using either the specified file pointer (R0 = 3) or the current one (R0 = 4). If the specified pointer is greater than the current file extent then no bytes are read, and the sequential file pointer is not updated. Otherwise the sequential file pointer is set to the specified file location.
The memory pointer is incremented for each byte read, and the final value is returned in R2. R3 is decremented for each byte read. If it is zero on exit (all the bytes were read), the carry flag will be clear, otherwise it is set. The sequential pointer of the file is incremented for each byte read, and the final value is returned in R4.
The EOF-error-on-next-read flag is cleared.
An error is generated if the file handle is invalid; also if the file is a directory, or does not have read access.
R0 = 5, 6 or 7
R2 = start address of buffer in memory
R0, R2 preserved
C flag corrupted
These calls read information on the temporary filing system (normally the current one) to the buffer pointed to by R2. The value you pass in R0 determines the nature and format of the data, which is always byte-oriented:
If R0 = 5, the call reads the name of the disc which contains the current directory, and its boot option. It is returned as:
<name length byte><disc name><boot option byte>
The boot option byte may contain values other than 0 - 3; under RISC OS 3 it always contains 0.
<zero byte><name length byte><current directory name><privilege byte>
The privilege byte is &00 if you have 'owner' status (ie can create and delete objects in the directory) or &FF if you have 'public' status (ie are prevented from creating and deleting objects in the directory). On ADFS and other FileCore-based filing systems you always have owner status.
<zero byte><name length byte><library directory name><privilege byte>
The version of NetFS supplied with RISC OS 2 (5.46) pads disc and directory names to the right with spaces; other filing systems do not, including the version of NetFS supplied with RISC OS 3 (5.69 or later). None of the names have terminators; so if the disc name were Mike, the name length byte would be 4.
R0 = 8
R2 = start address of data in memory
R3 = number of object names to read from directory
R4 = offset of first item to read in directory (0 for start)
R0, R2 preserved
R3 = number of objects asked for but not read
R4 = next offset in directory
C flag is clear if R3=0, else set
This call reads entries from the current directory on the temporary filing system (normally the current one). You can also do this using OS_GBPB 9.
R3 contains the number of object names to read. R4 is the offset in the directory to start reading (ie if it is zero, the first item read will be the first file). Filenames are returned in the area of memory specified in R2. The format of the returned data is:
| length of first object name | (one byte) |
| first object name in ASCII | (length as specified) |
| ... repeated as specified by R3 ... | |
| length of last object name | (one byte) |
| last object name in ASCII | (length as specified) |
If R3 is zero on exit, the carry flag will be cleared, otherwise it will be set. If R3 has the same value on exit as on entry then no more entries can be read and you must not call OS_GBPB 8 again.
On exit, R4 contains the value which should be used on the next call (to read more names), or -1 if there are no more names after the ones read by this call. There is no guarantee that the number of objects you asked for will be read. This is because of the external constraints some filing systems may impose. To ensure reading all the entries you want to, this call should be repeated until R4 = -1.
This call is only provided for compatibility with older programs.
Read entries and file information from a specified directory
R0 = 9, 10, 11 or 12
R1 = pointer to directory name (control-character or null terminated)
R2 = pointer to buffer (word aligned if R0 = 10, 11 or 12)
R3 = number of object names to read from directory
R4 = offset of first item to read in directory (0 for start)
R5 = buffer length
R6 = pointer to (wildcarded) name to match
R0 - R2 preserved
R3 = number of objects read
R4 = offset of last item read (-1 if finished)
R5, R6 preserved
C flag is clear if R3=0, else set
These calls read entries from a specified directory. If R0 = 10, 11 or 12 on entry the call also reads file information. If the directory name (which may contain wildcards) is null (ie R1 points to a zero byte), then the currently-selected directory is read.
The names which match the wildcard name pointed to by R6 are returned in the buffer. If R6 is zero or points to a null string then '*' is used, and all files will be matched. R3 indicates how many were read. R4 contains the value which should be used on the next call (to read more names), or -1 if there are no more names after the ones read by this call.
There is no guarantee that the number of objects you asked for will be read. This is because of the external constraints some filing systems may impose. To ensure reading all the entries you want to, this call should be repeated until R4 = -1.
If R0 = 9 on entry, the buffer is filled with a list of null-terminated strings consisting of the matched names.
If R0 = 10 on entry, the buffer is filled with records:
| Offset | Contents |
|---|---|
| 0 | Load address |
| 4 | Execution address |
| 8 | Length |
| 12 | File attributes |
| 16 | Object type |
| 20 | Object name (null terminated) |
Each record is word-aligned.
If R0 = 11 on entry, the buffer is filled with records:
Each record is word-aligned.
If R0 = 12 on entry, the buffer is filled with records:
| Offset | Contents |
|---|---|
| 0 | Load address, or high byte of date stamp (top three bytes are &000000) |
| 4 | Execution address, or low byte of date stamp |
| 8 | Length |
| 12 | File attributes |
| 16 | Object type |
| 20 | Object file type (as for OS_File 20-23) |
| 24 | Object name (null terminated) |
Each record is word-aligned.
Note that even if R3 returns with 0, the buffer area may still have been overwritten: for instance, it may contain filenames which did not match the wildcard name pointed to by R6.
An error is generated if the directory could not be found.
OS_GBPB 12 is not available in RISC OS 2.
R0 = reason code
Other registers depend on reason code
Depends on reason code
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call opens and closes files.
If the low byte of R0 = 0 on entry, then you can either close a single file, or all files on the current filing system; see OS_Find 0 on OS_Find 0.
If the low byte of R0 0 on entry then a file is opened for byte access. You can open files in the following ways:
When you open a file a unique file handle is returned to you. You need this for any calls you make to OS_Args, OS_BGet, OS_BPut and OS_GBPB, and to eventually close the file using OS_Find 0. For full details of the reason codes to open files, see OS_Find 64 to 255 on OS_Find 64 to 255.
None
FindV
Closes files
R0 = 0
R1 = file handle, or zero to close all files on current filing system
Registers preserved
This call closes files. Any modified data held in RAM buffers is first written to the file(s).
If R1 = 0 on entry, then all files on the current filing system are closed. You should not use this facility within a program that runs in a multi-tasking environment such as the desktop, as it may close files being used by other programs.
Otherwise R1 must contain a file handle, that was returned by the earlier call of OS_Find that opened the file. Regardless of any errors returned, the file will always be closed on return from this call.
R0 = reason code
R1 = pointer to object name
R2 = optional pointer to path string or path variable
R0 = file handle, or 0 if object doesn't exist
R1 and R2 preserved
These calls open files. The way the file is opened is determined by bits 6 and 7 of R0:
| R0 | Action |
|---|---|
| &4X | open an existing file with read access only |
| &8X | create a new file with read/write access |
| &CX | open an existing file with read/write access |
In fact there is no guarantee that you will get the access that you are seeking, and if you don't no error is returned at open time. The exact details depend on the filing system being used, but as a guide this is what any new filing system should do if the object is an existing file:
| R0 | Action |
|---|---|
| &4X | Return a handle if it has read access. Generate an error if it has not got read access. |
| &8X | Generate an error if it is locked, or has neither read nor write access. Otherwise return a handle, and open the file with its existing access, and with its extent set to zero. |
| &CX | Generate an error if it is locked and has no read access, or has neither read nor write access. Otherwise return a handle, and open the file with its existing access. |
The access granted is cached with the stream, and so you cannot change the access permission on an open file.
Bits 4 and 5 of R0 currently have no effect, and should be cleared.
Bit 3 of R0 determines what happens if you try to open an existing file (ie R0 = &4X or &CX), but it doesn't exist:
| Bit 3 | Action |
|---|---|
| 0 | R0 is set to zero on exit |
| 1 | an error is generated |
Bit 2 of R0 determines what happens if you try to open an existing file (ie R0 = &4X or &CX) but it is a directory:
| Bit 2 | Action |
|---|---|
| 0 | you can open the directory but cannot do any operations on it |
| 1 | an error is generated |
If you are creating a new file (ie R0 = &8X) then an error is always generated if the object is a directory.
Bits 1 and 0 of R0 determine what path is used to search for the file:
| Bit 1 | Bit 0 | Path used |
|---|---|---|
| 0 | 0 | File$Path system variable |
| 0 | 1 | path string pointed to by R2 |
| 1 | 0 | path variable, name of which is pointed to by R2 |
| 1 | 1 | none |
For a description of the path strings that are held in path variables, see the chapter entitled File$Path and Run$Path.
In all cases the file pointer is set to zero. If you are creating a file, then the extent is also set to zero.
Note that you need the file handle returned in R0 for any calls you make to OS_Args, OS_BGet, OS_BPut and OS_GBPB, and to eventually close the file using OS_Find 0.
Controls the filing system manager and filing systems
R0 = reason code
Other registers depend on reason code
R0 preserved
Other registers depend on reason code
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call controls the filing system manager and filing systems. It is indirected through FSCV.
The particular action of OS_FSControl is given by the reason code in R0 as follows:
| R0 | Action | Page |
|---|---|---|
| 0 | Set the current directory | OS_FSControl 0 |
| 1 | Set the library directory | OS_FSControl 1 |
| 2 | Inform of start of new application | OS_FSControl 2 |
| 3 | Reserved for internal use | -- |
| 4 | Run a file | OS_FSControl 4 |
| 5 | Catalogue a directory | OS_FSControl 5 |
| 6 | Examine the current directory | OS_FSControl 6 |
| 7 | Catalogue the library directory | OS_FSControl 7 |
| 8 | Examine the library directory | OS_FSControl 8 |
| 9 | Examine objects | OS_FSControl 9 |
| 10 | Set filing system options | OS_FSControl 10 |
| 11 | Set the temporary filing system from a named prefix | OS_FSControl 11 |
| 12 | Add a filing system | OS_FSControl 12 |
| 13 | Check for the presence of a filing system | OS_FSControl 13 |
| 14 | Filing system selection | OS_FSControl 14 |
| 15 | Boot from a filing system | OS_FSControl 15 |
| 16 | Filing system removal | OS_FSControl 16 |
| 17 | Add a secondary module | OS_FSControl 17 |
| 18 | Decode file type into text | OS_FSControl 18 |
| 19 | Restore the current filing system | OS_FSControl 19 |
| 20 | Read location of temporary filing system | OS_FSControl 20 |
| 21 | Return a filing system file handle | OS_FSControl 21 |
| 22 | Close all open files | OS_FSControl 22 |
| 23 | Shutdown filing systems | OS_FSControl 23 |
| 24 | Set the attributes of objects | OS_FSControl 24 |
| 25 | Rename objects | OS_FSControl 25 |
| 26 | Copy objects | OS_FSControl 26 |
| 27 | Wipe objects | OS_FSControl 27 |
| 28 | Count objects | OS_FSControl 28 |
| 29 | Reserved for internal use | -- |
| 30 | Read location of secondary module for temporary filing system | OS_FSControl 30 |
| 31 | Convert a string giving a file type to a number | OS_FSControl 31 |
| 32 | Output a list of object names and information | OS_FSControl 32 |
| 33 | Convert a file system number to a file system name | OS_FSControl 33 |
| 34 | Reserved for future expansion | -- |
| 35 | Add an image filing system | OS_FSControl 35 |
| 36 | Image filing system removal | OS_FSControl 36 |
| 37 | Convert a pathname to a canonicalised name | OS_FSControl 37 |
| 38 | Convert file information to an object's file type | OS_FSControl 38 |
| 39 | Set the User Root Directory (URD) | OS_FSControl 39 |
| 40 | Exchange current and previous directories | OS_FSControl 40 |
| 41 | Return the defect list for an image | OS_FSControl 41 |
| 42 | Map out a defect from an image | OS_FSControl 42 |
| 43 | Unset the current directory | OS_FSControl 43 |
| 44 | Unset the User Root Directory (URD) | OS_FSControl 44 |
| 45 | Unset the library directory (Lib) | OS_FSControl 45 |
| 46 | Return an image file's used space map | OS_FSControl 46 |
| 47 | Read the boot option of the disc or image file that holds a specified object | OS_FSControl 47 |
| 48 | Write the boot option of the disc or image file that holds a specified object | OS_FSControl 48 |
| 49 | Read the free space on the disc or image file that holds a specified object | OS_FSControl 49 |
| 50 | Name the disc or image file that holds a specified object | OS_FSControl 50 |
| 51 | Request that an image stamp be updated | OS_FSControl 51 |
| 52 | Find the name and type of object that uses a particular offset | OS_FSControl 52 |
| 53 | Set a specified directory to a given path without verification | OS_FSControl 53 |
| 54 | Read the path of a specified directory | OS_FSControl 54 |
For details of each of these reason codes (except those reserved for internal use), see the given pages.
Reason codes 35 upwards are not available under RISC OS 2.
None
FSCV
R0 = 0
R1 = pointer to (wildcarded) directory name
Registers preserved
This call sets the current directory to the named one. If the name specifies a different filing system, it also selects that as the current filing system. If the name pointed to is null, the directory is set to the user root directory.
R0 = 1
R1 = pointer to (wildcarded) directory name
Registers preserved
This call sets the library directory on a filing system. If no filing system is specified, then the temporary filing system's library is set. If the name pointed to is null, the library directory is set to the filing system default (typically $.Library, if present).
Whenever a reference is made to the library on a specific filing system (eg net:%.Link), that filing system's library is used; if no filing system is specified (eg (%.Link), the temporary filing system's library is used.
If a filing system does not have a library directory set, then it searches in order the directories &.Library, $.Library and @. Under RISC OS 2, filing systems that are not FileCore based search % instead.
Informs RISC OS and the current application that a new application is starting
R0 = 2
R1 = pointer to command tail to set
R2 = currently active object pointer to write
R3 = pointer to command name to set
Registers preserved - may not return
This call enables you to start up an application by hand, setting its environment string to a particular value; and allows FileSwitch and the kernel to free resources related to the current thread.
First of all, FileSwitch calls XOS_UpCall 256 (new application starting - see OS_UpCall 256), with R2 set to the currently active object pointer that may be written.
If the UpCall is claimed, this means that someone is refusing to let your new application be started, so the error 'Unable to start application' is returned.
FileSwitch then calls XOS_ServiceCall &2A (Service_NewApplication - see Service_NewApplication (Service Call &2A)), with R2 set to the currently active object pointer that may be written.
If the Service is claimed, this means that some module is refusing to let your new application be started; however an error cannot be returned as your calling task has just been killed, and FileSwitch would be returning to it. So FileSwitch generates the 'Unable to start application' error using OS_GenerateError (see OS_GenerateError); this will be sent to the error handler of your calling task's parent, since your calling task will have restored its parent's handlers on receiving the UpCall 256.
Next, unless the Exit handler is below MemoryLimit, all handlers that are
still set below MemoryLimit are reset to the default handlers (see OS_ReadDefaultHandler, OS_ReadDefaultHandler).
The currently active object pointer is then set to the value given and the environment string set up to be that desired. The current time is read into the environment time variable (see OS_GetEnv, OS_GetEnv).
FileSwitch frees any temporary strings and transient blocks it has allocated and sets the temporary filing system to the current filing system.
If the call returns with V clear, all is set for your task to start up the application:
MOV R0, #FSControl_StartApplication
LDR R1, command_tail_ptr
LDR R2, execution_address
BIC R2, R2, #&FC000003 ; Address with no flags, USR mode
LDR R3, command_name_ptr
SWI XOS_FSControl
BVS return_error
; if in supervisor mode here, need to flatten SVC stack
; LDR R13, InitSVCStack
TEQP PC, #0 ; USR mode, interrupts enabled
MOV R0, R0 ; No op to avoid contention
MOV R12, #&80000000 ; Ensure called appl'n doesn't
MOV R13, #&80000000 ; assume a stack or workspace
MOV R14, PC ; Form return address
MOV PC, R2 ; Enter appl'n: assumes CAO = exec
SWI OS_Exit ; In case it returns
R0 = 4
R1 = pointer to (wildcarded) filename
Registers preserved
This call runs a file. If a matching object is a directory then it is ignored, unless it contains a !Run file. The first file, or directory.!Run file that matches is used:
This call may never return. If it is starting up a new application then the UpCall handler is notified, so any existing application has a chance to tidy up or to forbid the new application to start. It is only after this that the new application might be loaded.
The file is searched for using the variable Run$Path. If this does not exist, a path string of ',%.' is used (ie the current directory is searched first, followed by the library directory).
You cannot kill FileSwitch while it is threaded; so if you had an Obey file with the line:
RMKill FileSwitch
this will not work if the file is *Run, but would if you were to use *Obey.
An error is generated if the file is not matched, or does not have read access, or is a date/time stamped file without a corresponding Alias$@RunType variable.
R0 = 5
R1 = pointer to (wildcarded) directory name
Registers preserved
This call outputs a catalogue of the named subdirectory, relative to the current directory. If the name pointed to is null, the current directory is catalogued.
An error is returned if the directory does not exist, or the object is a file.
R0 = 6
R1 = pointer to (wildcarded) directory name
Registers preserved
This call outputs information on all the objects in the named subdirectory, relative to the current one. If the name pointed to is null, the current directory is examined.
An error is returned if the directory does not exist, or the object is a file.
R0 = 7
R1 = pointer to (wildcarded) directory name
Registers preserved
This call outputs a catalogue of the named subdirectory, relative to the current library directory. If the name pointed to is null, the current library directory is catalogued.
An error is returned if the directory does not exist, or the object is a file.
R0 = 8
R1 = pointer to (wildcarded) directory name
Registers preserved
This call outputs information on all the objects in the named subdirectory, relative to the current library directory. If the name pointed to is null, the current library directory is examined.
An error is returned if the directory does not exist, or the object is a file.
R0 = 9
R1 = pointer to (wildcarded) pathname
R0 preserved
This call outputs information on all objects in the specified directory matching the wild-leaf-name given.
An error is returned if the pathname pointed to is null.
R0 = 10
R1 = option (0, 1 or 4)
R2 = parameter
Registers preserved
This call sets filing system options on the temporary filing system (normally the current one). An option of 0 means reset all filing system options to their default values. See the *Opt command (*Opt 1) for full details.
R0 = 11
R1 = pointer to string
R0 preserved
R1 = pointer to part of name past the filing system specifier if present
R2 = -1 no filing system was specified (call has no effect)
R2 0 old filing system to be reselected
R3 = pointer to special field, or 0 if none present
This call sets the temporary filing system from a filing system prefix at the start of the string, if one is present. It is used by OS_CLI to set temporary filing systems for the duration of a command.
You can restore the temporary filing system to be the current one by calling OS_FSControl 19.
Add a filing system
R0 = 12
R1 = module base address
R2 = offset of the filing system information block from the module base
R3 = private word pointer
R0 - R3 preserved
This call informs FileSwitch that a module is a new filing system, to be added to the list of those it knows about. The module should make this call when it initialises.
R1 and R2 give the location of a filing system information block, which is used by FileSwitch to communicate with the filing system module. It contains both information about the filing system, and the location of entry points to the module's code.
The private word pointer passed in R3 is stored by FileSwitch. When it makes a call to the filing system module, the private word is passed in R12. Normally, this private word is the workspace pointer for the module.
For full information on writing a filing system module, see the chapter entitled Writing a filing system.
R0 = 13
R1 = filing system number (see Filing system numbers), or pointer to filing system name
R2 = R1 dependent
R0 preserved
R1 = filing system number (see Filing system numbers), or preserved if not found
R2 = pointer to filing system control block, or 0 if not found
This call checks for the presence of a filing system.
If R1 < &100 then it is the filing system number (see Filing system numbers); if, however, R1 &100 then it points to the filing system name. The filing system name match is case-insensitive. If R2 is 0, the filing system name is taken to be terminated with any control character or the characters: '#', ':' or '-'. If R2 is not 0, then the filing system name is terminated by any control character.
The filing system control block that is pointed to by R2 on exit is for the internal use of FileSwitch, and you should not use or alter it. You should only test the value of R2 for equality (or not) with zero.
An error is returned if the filing system name contains bad characters or is badly terminated.
R0 = 14
R1 = filing system number (see Filing system numbers), or pointer to filing system name
Registers preserved
This call switches the current and temporary filing systems to the one specified by R1.
If R1 = 0 then no filing system is selected as the current or temporary one (the settings are cleared). If R1 is < &100 it is assumed to be a filing system number (see Filing system numbers). Otherwise, it must be a pointer to a filing system name, terminated by a control-character or one of the characters '#', ':' or '-'. The filing system name match is case-insensitive.
This call is issued by filing system modules when they are selected by a * Command, such as *Net or *ADFS.
An error is returned if the filing system is specified by name and is not present.
R0 = 15
R0 preserved
This call boots off the currently selected filing system. It is called by the RISC OS kernel before entering the configured language module when the machine is reset using the Break key or reset switch, depending on the state of other keys, and on how the computer is configured.
This call may not return if boot runs an application.
For more details, see *Configure Boot, *Configure NoBoot, and the *Opt commands (*Opt 1).
R0 = 16
R1 = pointer to filing system name
Registers preserved
This call removes the filing system from the list held by FileSwitch. It calls the filing system to close open files, flush buffers, and so on (except under RISC OS 2). You should use it in the finalise entry of a filing system module.
Filing systems must be removed on any type of finalisation call, and added (including any relevant secondary modules) on any kind of initialisation. The reason for this is that FileSwitch keeps pointers into the filing system module code, which may be moved as a result of tidying the module area or other such operations.
R1 must be a pointer to a control-character terminated name - you cannot remove a filing system by file system number, and if you try to do so an error is returned.
Modules must not complain about errors in filing system removal. Otherwise, it would be impossible to reinitialise the module after reinitialising the filing system manager.
Under RISC OS 2, if the filing system is the temporary one then the temporary filing system is set to the current filing system. If the filing system is the current one, then both the current and temporary filing systems are set to 0 (none currently selected), and the old filing system number is stored. If it is added again before a new current filing system is selected then it will be reselected (see OS_FSControl 12 on OS_FSControl 12).
Add a secondary module
R0 = 17
R1 = pointer to filing system name
R2 = pointer to secondary system name
R3 = secondary module workspace pointer
Registers preserved
This call is used to add secondary modules, so that extra filing system commands are recognised in addition to those provided by the primary filing system module. It is mainly used by FileCore (a primary module) to add its secondary modules such as ADFS.
R0 = 18
R2 = file type (bits 0 - 11)
R0 preserved
R2 = first four characters of textual file type
R3 = second four characters of textual file type
This call issues OS_ServiceCall &42 (see Service_LookupFileType (Service Call &42)). If the service is unclaimed, then it builds a default file type. For example if the file type is:
Command
the call packs the four bytes representing the characters:
"Comm" - in R2
and the four bytes:
"and " - in R3
The string is padded on the right with spaces to a maximum of 8.
This BASIC code converts the file type in filetype% to a string in filetype$, terminated by a carriage return:
DIM str% 8 SYS "OS_FSControl", 18,,filetype% TO ,,r2%,r3% str%!0 = r2% str%!4 = r3% str%?8 = 13 filetype$ = $str%
OS_FSControl 31 (see OS_FSControl 31) does the opposite conversion - a textual file type to a file type number.
Restore the current filing system
R0 = 19
R0 preserved
This call sets the temporary filing system back to the current filing system.
OS_CLI (see OS_CLI) uses OS_FSControl 11 (see OS_FSControl 11)to set a temporary filing system before a command; it uses this call to restore the current filing system afterwards. This command is also called by the kernel before it calls the error handler.
R0 = 20
R0 preserved
R1 = primary module base address of temporary filing system
R2 = pointer to private word of temporary filing system
This call reads the location of the primary module for the temporary filing system, and its private word. (For example, if ADFS were the temporary filing system, this call would return FileCore's address, whereas OS_FSControl 30 would return the address of ADFS - the secondary module. However, if NetFS were the temporary filing system, this call would return its address.)
If no temporary filing system is set, then this call reads the values for the current filing system instead. If there is no current filing system then R1 will be zero on exit, and R2 undefined.
R0 = 21
R1 = file handle
R0 preserved
R1 = filing system file handle
R2 = filing system information word
This call takes a file handle used by FileSwitch, and returns the internal file handle used by the filing system which it belongs to. It also returns a filing system information word. For a full definition of this, see the chapter entitled Filing system information word.
The call returns a filing system file handle of 0 if the FileSwitch file handle is invalid.
You should only use this call to implement a filing system.
R0 = 22
R0 preserved
This call closes all open files on all filing systems. It first ensures that any modified buffered data remaining in RAM (either in FileSwitch or in filing system buffers) is written to the appropriate files.
The call does not stop if an error is encountered, but goes on to close all open files. An error is returned if any individual close failed.
R0 = 23
R0 preserved
This call closes all open files on all filing systems. It first ensures that any modified buffered data remaining in RAM (either in FileSwitch or in filing system buffers) is written to the appropriate files.
It informs all filing systems of the shutdown; most importantly this implies that it:
The call does not stop if an error is encountered, but goes on to close all open files. An error is returned if any individual close failed.
R0 = 24
R1 = pointer to (wildcarded) pathname
R2 = pointer to attribute string
Registers preserved
This call gives the requested access to all objects in the specified directory whose names match the specified wild-leaf pattern.
If any of the characters in R2 are valid but inappropriate they are not faulted, but if they are invalid an error is returned. An error is also returned if the pathname pointed to is null, or if the pathname is not matched.
R0 = 25
R1 = pointer to current pathname
R2 = pointer to desired pathname
Registers preserved
This call renames an object. It is a 'simple' rename, implying that the source and destination are single objects which must reside on the same physical device, and hence on the same filing system.
An error is returned if the two objects are on different filing systems (checked by FileSwitch), or on different devices (checked by the filing system), or in different image files (checked by FileSwitch).
An error is also returned if the object is locked or is open, or if an object of the desired pathname exists, or if the directory referenced by the pathname does not already exist.
R0 = 26
R1 = pointer to source (wildcarded) pathname
R2 = pointer to destination (wildcarded) pathname
R3 = mask describing the action
R4 = optional inclusive start time (low 4 bytes)
R5 = optional inclusive start time (high byte, in bits 0 - 7)
R6 = optional inclusive end time (low 4 bytes)
R7 = optional inclusive end time (high byte, in bits 0 - 7)
R8 = optional pointer to extra information descriptor:
Registers preserved
This call copies objects, optionally recursing.
The source leafname may be wildcarded. The only wildcarded destination leafname allowed is '*', which means to make the leafname the same as the source leafname.
The bits of the action mask have the following meaning when set:
Buffers are considered for use in the following order, if they exist or their use is permitted:
If either the Wimp free memory or the RMA buffers are used, they are freed between each object copied.
If application memory is used then FileSwitch starts itself up as the current application to claim application space. If on the start application service a module forbids the start-up, then the copy is aborted and an error is generated to the Error handler of the parent of the task that called OS_FSControl 26. The call does not return; it sets the environment time variable to the time read when the copy started and issues SWI OS_Exit, setting Sys$ReturnCode to 0.
R0 = 27
R1 = pointer to wildcarded pathname to delete
R2 = not used
R3 = mask describing the action
R4 = optional start time (low 4 bytes)
R5 = optional start time (high byte, in bits 0 - 7)
R6 = optional end time (low 4 bytes)
R7 = optional end time (high byte, in bits 0 - 7)
Registers preserved
This call is used to delete objects. You can modify the effect of the call with the action mask in R3. Only bits 0 - 4 and 8 are relevant to this command. The function of these bits is as for OS_FSControl 26 (see OS_FSControl 26).
R0 = 28
R1 = pointer to wildcarded pathname to count
R2 = not used
R3 = mask describing the action
R4 = optional start time (low 4 bytes)
R5 = optional start time (high byte, in bits 0 - 7)
R6 = optional end time (low 4 bytes)
R7 = optional end time (high byte, in bits 0 - 7)
R0, R1 preserved
R2 = total number of bytes of all files that were counted
R3 = number of files counted
R4 - R7 preserved
This call returns information on the number and size of objects. You can modify the effect of the call with the action mask in R3. Only bits 0, 2 - 4 and 8 are relevant to this command. The function of these bits is as for OS_FSControl 26 (see OS_FSControl 26).
Note that the command returns the amount of data that each object is comprised of, rather than the amount of disc space the data occupies. Since a file normally has space allocated to it that is not used for data, and directories are not counted, any estimates of free disc space should be used with caution.
Read location of secondary module for temporary filing system
R0 = 30
R0 preserved
R1 = secondary module base address of temporary filing system
R2 = pointer to private word of temporary filing system
This call reads the location of the secondary module for the temporary filing system, and its private word. (For example, if ADFS were the temporary filing system, this call would return its address, whereas OS_FSControl 20 would return the address of FileCore - the primary module.)
If no temporary filing system is set, then this call reads the values for the current filing system instead. If there is no current filing system, or it does not have a secondary module, then R1 will be zero on exit, and R2 undefined.
R0 = 31
R1 = pointer to control-character terminated filetype string
R0, R1 preserved
R2 = filetype
This call converts the string pointed to by R1 to a file type. Leading and trailing spaces are skipped. The string may either be a file type name (spaces within which will not be skipped):
Obey Text
or represent a file type number (the default base of which is hexadecimal):
| FEB | Hexadecimal version of Obey file type number |
| 4_333333 | Base 4 version of Text file type number |
OS_FSControl 18 (see OS_FSControl 18) does the opposite conversion - a file type number to a textual file type.
R0 = 32
R1 = pointer to wildcarded pathname
Registers preserved
This call outputs a list of object names and information on them. The format is the same as for the *FileInfo command (see *FileInfo).
R0 = 33
R1 = filing system number (see Filing system numbers)
R2 = pointer to buffer
R3 = length of buffer
Registers preserved
This call converts the filing system number passed in R1 (see Filing system numbers) to a filing system name. The name is stored in the buffer pointed to by R2, and is null-terminated. If FileSwitch does not know of the filing system number you pass it, a null string is returned.
R0 = 35
R1 = module base address
R2 = offset of the image filing system information block from the module base
R3 = private word pointer
Registers preserved
This call informs FileSwitch that a module is a new image filing system, to be added to the list of those it knows about. The module should make this call when it initialises.
R1 and R2 give the location of an image filing system information block, which is used by FileSwitch to communicate with the image filing system module. It contains both information about the image filing system, and the location of entry points to the module's code.
The private word pointer passed in R3 is stored by FileSwitch. When it makes a call to the image filing system module, the private word is passed in R12. Normally, this private word is the workspace pointer for the module.
For full information on writing an image filing system module, see the chapter entitled Writing a filing system.
This call is not available in RISC OS 2.
R0 = 36
R1 = image filing system's file type
Registers preserved
This call removes the image filing system from the list held by FileSwitch. It calls the image filing system to close open files, flush buffers, and so on. You should use it in the finalise entry of an image filing system module.
Image filing systems must be removed on any type of finalisation call, and added on any kind of initialisation. The reason for this is that FileSwitch keeps pointers into the image filing system module code, which may be moved as a result of tidying the module area or other such operations.
R1 must be the image filing system's file type. You cannot remove a filing system by file system number, and if you try to do so an error is returned.
Modules must not complain about errors in filing system removal. Otherwise, it would be impossible to reinitialise the module after reinitialising the filing system manager.
This call is not available in RISC OS 2.
R0 = 37
R1 = pointer to pathname
R2 = pointer to buffer to contain null terminated canonicalised name
R3 = pointer to name of a path variable that contains a control-character terminated comma separated path string, or 0 if none
R4 = pointer to control-character terminated comma separated path string to use if variable not specified or non-existent, or 0 if none
R5 = size of buffer
R5 = number of spare bytes in the buffer including the null terminator, ie:
| R5 1
| there are (R5 - 1) completely unused bytes in the buffer; so R5 = 1 there are 0 unused bytes in the buffer, and therefore the terminator just fitted
|
| R5 0
| there are (1 - R5) too many bytes to fit in the buffer, which has consequently not been filled in; so R5 = 0 there is 1 byte too many - the terminator - to fit in the buffer
|
This call takes a pathname and returns its canonicalised name. However, case may differ, and wildcards may not be sorted out if the wildcarded object doesn't exist.
For example:
This may be used as a two-pass process:
On entry, set R1 to point to the pathname, and R2 and R5 (the pointer to, and size of, the buffer) to zero. On exit, R5 = -(length of canonicalised name)
Claim a buffer of the right size (1-R5, not just -R5, as a space is needed for the terminator). On entry, ensure that R1 still points to the pathname, that R2 is set to point to the buffer, and R5 contains the length of the buffer. On exit the buffer should be filled in, and R5 should be 1; but check to make sure.
This call is not available in RISC OS 2.
R0 = 38
R1 = pointer to the object's name
R2 = load address
R3 = execution address
R4 = object length
R5 = object attributes
R6 = object type (file/directory/image file)
R2 = object filetype
| Special values: | |
| -1 | untyped (entry R2 and R3 were load and execution address) |
| &1000 | directory |
| &2000 | application directory (directory whose name starts with a '!') |
This call converts file information, as returned by various calls - for example OS_File 5 - into the object's file type.
This call is not available in RISC OS 2.
Sets the User Root Directory (URD)
R0 = 39
R1 = pointer to User Root Directory
--
This call sets the User Root Directory, which is shown as an '&' in pathnames.
This call is not available in RISC OS 2.
R0 = 40
--
This call swaps the current and previously selected directories.
This call is not available in RISC OS 2.
R0 = 41
R1 = pointer to name of image (null terminated)
R2 = pointer to buffer
R5 = buffer length
R0 - R5 preserved
This call fills the given buffer with a defect list, which gives the byte offset to the start of each defect. The list is terminated by the value &20000000.
This call is not available in RISC OS 2.
This call returns incorrect information for NetFS.
R0 = 42
R1 = pointer to name of image (null terminated)
R2 = byte offset to start of defect
R0 - R2 preserved
This call maps out a defect from the given image.
This call is not available in RISC OS 2.
This call returns incorrect information for NetFS.
R0 = 43
--
This call unsets the current directory on the temporary filing system.
This call is not available in RISC OS 2.
R0 = 44
--
This call unsets the User Root Directory on the temporary filing system.
This call is not available in RISC OS 2.
R0 = 45
--
This call unsets the library directory on the temporary filing system.
This call is not available in RISC OS 2.
Returns an image file's used space map
R0 = 46
R1 = pointer to name of image (null terminated)
R2 = pointer to buffer
R5 = buffer length
R0 - R5 preserved
This call returns an image file's used space map, filling the given buffer with 0 bits for unused blocks, and 1 bits for used blocks. The buffer will be filled to its limit, or to 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. The correspondence of the buffer to the file is 1 bit to 1 block. The least significant bit (bit 0) in a byte comes before the most significant bit.
The used space is the total space excluding free space and defects.
For non-image files, the buffer will be filled with ones.
This call is not available in RISC OS 2.
Reads the boot option of the disc or image file that holds a specified object
R0 = 47
R1 = pointer to name of object (null terminated)
R0, R1 preserved
R2 = boot option
This call reads the boot option (ie the value n in *Opt 4,n) of the disc or image file that holds the specified object.
This call is not available in RISC OS 2.
Writes the boot option of the disc or image file that holds a specified object
R0 = 48
R1 = pointer to name of object (null terminated)
R2 = new boot option
R0 - R2 preserved
This call writes the boot option (ie the value n in *Opt 4,n) of the disc or image file that holds the specified object.
This call is not available in RISC OS 2.
Reads the free space on the disc or image file that holds a specified object
R0 = 49
R1 = pointer to name of object (null terminated)
R0 = free space
R1 = largest creatable object
R2 = disc size
This call reads the free space on the disc or image file that holds the specified object. It also returns the size of the largest creatable object, and the size of the disc.
This call is not available in RISC OS 2, and returns incorrect information for NetFS.
R0 = 50
R1 = pointer to name of object (null terminated)
R2 = new name of disc
R0 - R2 preserved
This call names the disc or image file that holds the specified object.
This call is not available in RISC OS 2.
Used by a handler of discs to request that an image stamp be updated
R0 = 51
R1 = pointer to name of object (null terminated)
R2 = sub-reason code:
| 0 | stamp when updated |
| 1 | stamp now |
R0 - R2 preserved
This call is made by a handler of discs (eg FileCore) to inform an image filing system (eg DOSFS) that it should update the disc's image stamp (a unique identification number), either when the disc is next updated (R2=0), or now (R2=1).
See the chapter entitled Writing a filing system for more details.
This call is not available in RISC OS 2.
Finds the name and type of object that uses a particular offset within an image
R0 = 52
R1 = pointer to name of object (null terminated)
R2 = offset into disc or image
R3 = pointer to buffer to receive object name (if object found)
R4 = buffer length
R2 = kind of object found at offset:
| 0 | no object found; offset is free/a defect/beyond end of image |
| 1 | no object found; offset is allocated, but not (free / a defect / beyond end of image) - eg the free space map |
| 2 | object found; cannot share the offset with other objects |
| 3 | object found; can share the offset with other objects |
This call finds the name and type of object that uses a particular offset within an image. On exit, if R2 = 2 or 3 then an object has been found, and the buffer will contain its full pathname; otherwise the buffer may be corrupted.
The image searched is the deepest image, eg if R1 pointed to:
$.pc.amiga.atari.a.b.c
where pc is a DOS disc image, amiga is an Amiga disc image, and atari an Atari disc image, then the image searched would be:
$.pc.amiga.atari
This call is not available in RISC OS 2.
Sets a specified directory to a given path without verification
R0 = 53
R1 = pointer to rest of path
R2 = directory to set
R3 = pointer to name of filing system (null-terminated)
R6 = pointer to special field (terminated by a null or '.'), or 0 if not present
Registers preserved
This call explicitly tells FileSwitch to set the specified directory to the given path without it performing any form of verification on the path provided.
The 'rest of path' is a string giving 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 null-terminated. It must have a root directory of some sort (ie $, % or & must be present at the right place). For example:
If R1 is 0 on entry then the relevant directory will be put into the unset state.
The value in R2 tells FileSwitch which directory to set:
| Value | Directory | |
|---|---|---|
| 0 | @ | (currently selected directory) |
| 1 | \ | (previously selected directory) |
| 2 | & | (user root directory) |
| 3 | % | (library) |
Other values are illegal.
The optional special field pointed to by R6 should consist of the textual part of the special field, after any # prefix that may have been present. It is terminated by a null byte or a '.'. It must not contain any wildcards or GSTransable bits.
This call is not available in RISC OS 2.
R0 = 54
R1 = pointer to buffer
R2 = directory to read
R3 = pointer to name of filing system (null-terminated)
R5 = size of buffer, or 0 to get required size of buffer
R1 = pointer to rest of path, or 0 if directory unset
R5 = value on entry, decremented by total size of data placed in buffer
R6 = pointer to special field (terminated by a null or '.'), or 0 if not present
This call reads the path of a specified directory. It is the reverse of OS_FSControl 53 (see OS_FSControl 53). It is expected that this call will be used twice, the first time to get the buffer length (ie R5 = 0 on entry, on exit is decremented by required length), and 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 OS_FSControl 53.
This call is not available in RISC OS 2.
Controls who can run, read from, write to and delete specific files
*Access object_spec [attributes]
object_spec - a valid (wildcarded) pathname specifying a file or directory
attributes - The following attributes are allowed:
L - Lock object against deletion by any user
W - Write permission for you
R - Read permission for you
/ - Separator between your permissions and the public's
W - Write permission for the public (on NetFS)
R - Read permission for the public (on NetFS)
*Access changes the attributes of all objects matching the wildcard specification. These attributes control whether you can run, read from, write to and delete a file.
NetFS uses separate attributes to control other people's read and write access to your files: their 'public access'. By default, files are created without public read and write permission. If you want others on the network to be able to read files that you have created, make sure you have explicitly changed the access status to include public read. If you are willing to have other NetFS users work on your files (ie overwrite them), set the access status to public write permission. Other NetFS users cannot completely delete your files though, unless they have owner access.
The public attributes can be set within any FileCore-based filing system, except when using L-format; but they will be ignored unless the file is transferred to the NetFS. Other filing systems may work in the same way, or may generate an error if you try to use the public attributes.
*access myfile l
*access myfile wr/r
*Ex, *FileInfo, *Info
*Append filename
filename - a valid pathname specifying an existing file
*Append opens an existing file so you can add more data to the end of the file. Each line of input is passed to OS_GSTrans before it is added to the file. Pressing Escape finishes the input.
*type thisfile this line is already in thisfile *append thisfile 1 some more text
Esc - the Esc character terminates the file
*type thisfile this line is already in thisfile some more text
*Build
*Back
*Back swaps the current and previously selected directories on the current filing system. The command is used for switching between two frequently used directories.
In RISC OS 2 this command is implemented by FileCore.
*Dir
Opens a new file (or overwrites an existing one) and directs subsequent input to it
*Build filename
filename - a valid pathname specifying a file
*Build opens a new file (or reopens an existing one with zero extent) and directs subsequent input to it. Each line of input is passed to OS_GSTrans before it is added to the file. Pressing Escape finishes the input.
Note that for compatibility with earlier systems the *Build command creates files with lines terminating in the carriage return character (ASCII &0D). The Edit application provides a simple way of changing this into a linefeed character, using the CR
LF function from the Edit submenu.
*Build testfile 1 This is the first line of testfile
Esc - the Esc character terminates the file
*Type testfile This is the first line of testfile
*Append
*Cat [directory]
directory - a valid pathname specifying a directory
*Cat (short for 'catalogue') lists all the objects in a directory, showing their access attributes, and other information on the disc name, options set, etc. If no directory is specified, the contents of the current directory are shown. *Cat can be abbreviated to '*.' (a full stop), provided that you have not *Set the system variable Alias$. to a different value from its default.
| *. | catalogue of current directory |
| *cat net#59.254: | catalogue of current directory on NetFS file server 59.254 |
| *.ram:$.Mike | catalogue of RAM filing system directory $.Mike |
| *Cat { > printer: } | catalogue of current directory redirected to printer |
*Ex, *FileInfo, *Info, *LCat and *LEx
*CDir directory [size_in_entries]
directory - a valid pathname specifying a directory
size_in_entries - how many entries the directory should hold before it needs to be expanded (NetFS is the only built-in filing system to use this)
*CDir creates a directory with the specified pathname. On the NetFS, and on some third-party filing systems, you can also give the size of the directory.
| *CDir fred | creates a directory called fred on the current filing system, as a daughter to the current directory |
| *CDir ram:fred | creates a directory called fred on the RAM filing system, as a daughter to the current RAMFS directory |
*Cat
*Close
None
*Close closes all open files on the current filing system, and is useful when a program crashes, leaving files open.
If preceded by the filing system name, *Close can be used to close files on systems other than the current one. For example:
*adfs:Close
would close all files on ADFS, no matter which filing system is the current one.
You must not use this command within a program that runs in a multi-tasking environment such as the desktop, as it may close files being used by other programs.
*Bye, *Shut, *Shutdown
Sets the configured boot action so that a power on, reset or Ctrl Break runs a boot file
*Configure Boot
None
*Configure Boot sets the configured boot action so that a power on, reset or Ctrl Break runs a boot file, provided that the Shift key is not held down - if it is, then no boot takes place.
When a boot does take place, the file &.!Boot is looked for, and if found is loaded and run, as set by the *Opt 4 command. You might use a boot file to load a program automatically when the computer is switched on. For information on NetFS boot files, see your network manager.
You can use the *FX 255 command to override the configured boot action at any time; a typical use is to disable booting at the end of a boot file, so that the computer does not re-boot on a soft reset.
The Break key always operates as an Escape key after power on.
NoBoot is the default setting.
The change takes effect on the next power-on or hard reset.
*Configure NoBoot, *FX 255
Sets the configured format used by the *Dump, *List and *Type commands
*Configure DumpFormat n
n - A number in the range 0 to 15. The parameter is treated as a four-bit number.
The bottom two bits define how control characters are displayed, as follows:
| Value | Meaning |
|---|---|
| 0 | GSTrans format is used (eg |A for ASCII 1) |
| 1 | Full stop '.' is used |
| 2 | <d> is used, where d is a decimal number |
| 3 | <&h> is used, where h is a hexadecimal number |
If bit 2 is set, characters which have their top bit set are treated as printable characters; otherwise they are treated as control characters. n=5, for example, causes ASCII character 247 to be printed as ÷ (Latin fonts only).
If bit 3 is set, characters which have their top bit set are ANDed with &7F before being processed so the top bit is no longer set; otherwise they are left as they are.
*Configure DumpFormat sets the configured format used by the *Dump, *List and *Type commands, and the vdu: output device. The default value is 4 (GSTrans format, and characters with the top bit set are printed using all 8 bits).
*Dump ignores the setting of the bottom two bits of the parameter, and always prints control characters as full stops.
The change takes effect immediately.
*Configure DumpFormat 2
*Dump, *List, *Type
Sets the configured filing system to be used at power on or hard reset
*Configure FileSystem fs_name | fs_number
fs_name - a filing system name (ADFS, Net or Ram)
fs_number - a filing system number (see Filing system numbers)
*Configure FileSystem sets the configured filing system to be used at power on or hard reset. The filing system is selected just before any boot action is taken, and a banner is displayed showing its name. (The banner is also shown on a soft reset.)
To specify the filing system by name (rather than by number), FileSwitch must have that name registered at the time you use this command. This is because FileSwitch needs to convert the name to the filing system number that is actually stored.
If the configured filing system is not found on a reset then FileSwitch will return an error on every subsequent command that tries to use the currently selected filing system, until a current filing system is successfully selected.
*Configure FileSystem Net
Sets the configured boot action so that a Shift power on, Shift reset or Shift Break runs a boot file
*Configure NoBoot
None
*Configure NoBoot sets the configured boot action so that any kind of reset doesn't run a boot file - except if the Shift key is held down, when a boot takes place.
When a boot does take place, the file &.!Boot is looked for, and if found is loaded and run, as set by the *Opt 4 command. You might use a boot file to load a program automatically when the computer is switched on. For information on NetFS boot files, see your network manager.
You can use the *FX 255 command to override the configured boot action at any time; a typical use is to disable booting at the end of a boot file, so that the computer does not re-boot on a soft reset.
The Break key always operates as an Escape key after power on.
This is the default setting.
The change takes effect on the next power-on or hard reset.
*Configure Boot, *FX 255, *Rename
Sets the configured value for whether or not filenames are truncated when too long
*Configure Truncate On|Off
On - long filenames are truncated
Off - long filenames are not truncated
*Configure Truncate sets the configured value for whether or not filenames are truncated when too long for a filing system to handle.
If you are writing a filing system that is unable to handle filenames over a certain length, you should examine the bit of CMOS that this command alters (see the chapter entitled Non-volatile memory (CMOS RAM)). If filename truncation is off, you should generate a 'Bad name' error if you are passed too long a filename; otherwise, you should truncate all filenames.
This command is not available in RISC OS 2.
*Configure Truncate On
None
*Copy source_spec destination_spec [[~]options]
source_spec - a valid (wildcarded) pathname specifying a file or directory
destination_spec - a valid (wildcarded, but see below for restrictions) pathname specifying a file or directory
options - upper- or lower-case letters, optionally separated by spaces
A set of default options is read from the system variable Copy$Options, which is set by the system as shown below. You can change these default preferences using the *Set command. You are recommended to type:
*Set Copy$Options <Copy$Options> extra_options
so you can see what the original options were before you added your extra ones. The default options are overruled by any given to the command.
To ensure an option is ON, include it in the list of options; to ensure it is OFF, immediately precede the option by a '~' (eg ~C~r to turn off the C and R options).
Important when you are copying files from ADFS to NetFS, for example, because it maintains the access rights on the files copied. You should set this option to be OFF when you are updating a common release on the network, to maintain the correct access rights on it.
Useful as a check when you have used a wildcard, to ensure that you are copying the files you want. Possible replies to the prompt for each file are Y(es) (to copy the file or structure and then proceed to the next item), N(o) (to go on to the next item without making a copy), Q(uiet) (to copy the item and all subsequent items without further prompting), A(bandon) (to stop copying at the current level - see the R option), or Esc (to stop immediately).
This is useful for moving a file from one disc or other storage unit to another. The source object is copied; if the copy is successful, the source object is then deleted. If you want to move files within the same disc, the *Rename command is quicker, as it does not have to copy the files.
Performs the copy, regardless of whether the destination files exist, or what their access rights are. The files can be overwritten even if they are locked or have no write permission.
Files are normally copied by reading a large amount of data into memory before attempting to save it as a destination file. The L option checks the destination medium for accessibility before reading in the data. Thus L often saves time in copying, except for copies on the same disc.
This is useful during backups to prevent copying the same files each time, or for ensuring that you are copying the latest version of a file.
This is provided for compatibility with older filing systems and you should not need to use it. Most RISC OS filing systems will automatically prompt you to change media.
The Q option uses the application workspace, so overwrites whatever is there. It should not be used if an application is active.
Copying in the Desktop can use the Wimp's free memory, and so you should not need to use this option. It's quicker not to use this option when you are copying from hard disc to floppy, as these operations are interleaved so well. However, in other circumstances this option can speed up the copying operation considerably.
This is useful when copying several levels of directory, since it avoids the need to copy each of the directories one by one.
Useful for recording when the particular copy was made.
Copies the directory structure but not the files. By using this option as a first stage in copying a directory tree, access to the files is faster when they are subsequently copied.
This gives full textual commentary on the copy operation.
*Copy makes a copy between directories of any object(s) that match the given wildcard specification. Objects may be files or directories. The leafname of the destination must either be a specific filename, or the character '*' in which case the destination will have the same leafname as the source. For example:
*Copy data* Dir2.*
will copy all the files in the current directory with names beginning data to Dir2, preserving their leafnames.
Note that it is dangerous to copy a directory into one of its subsidiary directories. This results in an infinite loop, which only comes to an end when the disc is full or Esc is pressed.
If the Copy$Options variable is unset then *Copy behaves as if the variable were set to its default value.
*Copy fromfile tofile rfq~c~v
*Copy :fred.data* :jim.*
Copies all files beginning 'data' from the disc called 'fred' to the disc called 'jim'.
*Access, *Delete, *Rename, *Wipe, and the system variable Copy$Options.
Adds up the size of data held in file objects, and the number of objects
*Count object_spec [[~]options]
object_spec - a valid (wildcarded) pathname specifying a file or directory
options - upper- or lower-case letters, optionally separated by spaces
A set of default options is read from the system variable Count$Options, which is set by the system as shown below. You can change these default preferences using the *Set command. You are recommended to type:
*Set Count$Options <Count$Options> extra_options
so you can see what the original options were before you added your extra ones. The default options are overruled by any given to the command.
To ensure an option is ON, include it in the list of options; to ensure it is OFF, precede the option by a '~' (eg: ~C~r to turn off the C and R options).
This gives information on each file counted, rather than just printing the subtotal counted in directories.
*Count adds up the size of data held in one or more objects that match the given wildcard specification.
Note that the command returns the amount of data that each object is comprised of, rather than the amount of disc space the data occupies. Since a file normally has space allocated to it that is not used for data, and directories are not counted, any estimates of free disc space should be used with caution.
If the Count$Options variable is unset then *Count behaves as if the variable were set to its default value.
*Count $ r~cv
Counts all files on disc, giving full information on each file object
*Ex, *FileInfo, *Info, and the system variable Count$Options
*Create filename [length [exec_addr [load_addr>]]]
filename - a valid pathname specifying a file
length - the number of bytes to reserve (default 0)
exec_addr - the address to be jumped to after loading, if a program
load_addr - the address at which the file is loaded into RAM when *Loaded (default 0)
*Create reserves space for a new file, usually a data file. No data is transferred to the file. You may assign load and execution addresses if you wish. The units of length, load and execution addresses are in hexadecimal by default.
If both load and execution addresses are omitted, the file is created with type FFD (Data) and is date and time stamped.
*Create mydata 1000 0 8000
Creates a file &1000 bytes long, which will be loaded into address &8000
*Create newfile 10_4096
Creates a file &1000 bytes long which is date and time stamped
*Create bigfile &10000
*Load, *Save
Reports what object contains a defect, or (if none) marks the defective part of the disc so it will no longer be used
*Defect disc_spec disc_addr
disc_spec - the name of the disc or number of the disc drive
disc_addr - the hexadecimal disc address where the defect exists, which must be a multiple of 256 - that is, it must end in '00'
*Defect reports what object contains a defect, or (if none) marks the defective part of the disc so it will no longer be used. *Defect is typically used after a disc error has been reported, and the *Verify command has confirmed that the disc has a physical defect, and given its disc address.
If the defect is in an unallocated part of the disc, *Defect will render that part of the disc inaccessible by altering the 'map' of the disc.
If the defect is in an allocated part of the disc, *Defect tells you what object contains the defect, and the offset of the defect within the object. This may enable you to retrieve most of the information held within the object, using suitable software. You must then delete the object from the defective disc. *Defect may also tell you that some other objects must be moved: you should copy these to another disc, and then delete them from the defective disc. Once you have removed all the objects that the *Defect command listed, there is no longer anything allocated to the defective part of the disc; so you can repeat the *Defect command to make it inaccessible.
Sometimes the disc will be too badly damaged for you to successfully delete objects listed by the *Defect command. In such cases the damage cannot be repaired, and you must restore the objects from a recent backup.
In RISC OS 2 this command is implemented by FileCore.
*Verify mydisc Disc error 08 at :0/00010400 *Defect mydisc 10400 $.mydir must be moved .myfile1 has defect at offset 800 .myfile2 must be moved
*CheckMap, *Verify
*Delete object_spec
object_spec - a valid (wildcarded) pathname specifying a file or an empty directory
*Delete erases the single named file or empty directory. An error message is given if the object does not exist, or is a directory containing files.
You may not use wildcards in the last component of the pathname.
*Delete $.dir*.myfile
Uses wildcards
*Delete myfile
Deletes myfile from the current directory
*Remove, *Wipe
*Dir [directory]
directory - a valid pathname specifying a directory
*Dir selects a directory as the currently selected directory (CSD) on a filing system. You may set the CSD separately on each filing system, and on each server of a multi-server filing system such as NetFS. If no directory is specified, the user root directory (URD) is selected.
*Dir
sets the CSD to the URD
*Dir mydir
sets the CSD to mydir
A CSD may be set for each filing system, for instance, within NetFS, the command:
*Dir ADFS:...
sets the current filing system to ADFS and selects the CSD there; it does not affect the CSD in NetFS
whereas:
*ADFS:Dir...
sets the CSD on ADFS only; NetFS remains the current filing system
*Back, *CDir
Displays the contents of a file, in hexadecimal and ASCII codes
*Dump filename [file_offset [start_addr]]
filename - a valid pathname specifying a file
file_offset - offset, in hexadecimal by default, from the beginning of the file from which to dump the data
start_addr - display as if the file were in memory starting at this address (in hexadecimal by default) - defaults to the file's load address
*Dump displays the contents of a file as a hexadecimal and (on the righthand side of the screen) as an ASCII interpretation. An address is given on the lefthand side of:
start_addr + current offset in file
You can set the format used to display the ASCII interpretation using *Configure DumpFormat. This gives you control over:
If a file is time/date stamped, it is treated as having a load address of zero.
*Dump myprog 0 8000
Dumps the file myprog, starting from the beginning of the file (offset is 0) but numbering the dump from &8000, as if the file were loaded at that address
*Configure DumpFormat, *List, *Type
*EnumDir directory output_file [pattern]
directory - a valid pathname specifying a directory
output_file - a valid pathname specifying a file
pattern - a wildcard specification for matching against
*EnumDir creates a file of object leafnames from a directory that match the supplied wildcard specification.
The default pattern is *, which will match any file within a directory. The current directory can be specified by @.
*EnumDir $.dir myfile data*
Creates a file myfile, containing a list of all files beginning data contained in directory $.dir
*EnumDir @ listall *_doc
Creates a file listall, containing a list of all files in the current directory whose names end in _doc
*Cat, *LCat
*Ex [directory]
directory - a valid pathname specifying a directory
*Ex lists all the objects in a directory together with their corresponding file information. The default is the current directory.
Most filing systems also display an informative header giving the directory's name and other useful information.
*Ex mail Mail Owner DS Option 0 (Off) Dir. MHardy Lib. ArthurLib Current WR Text 15:54:37 04-Jan-1989 60 bytes LogFile WR Text 15:54:37 04-Jan-1989 314 bytes
*FileInfo, *Info
*Exec [filename]
filename - a valid pathname specifying a file
*Exec instructs the operating system to take its input from the specified file, carrying out the instructions it holds. This command is mainly used for executing a list of operating system commands contained in a command file. The file, once open, takes priority over the keyboard or serial input streams.
If no parameter is given, the current exec file is closed.
*Exec !Boot
uses the file !Boot as though its contents have been typed in from the keyboard
*Obey
None
*FileInfo object_spec
object_spec - a valid (wildcarded) pathname specifying one or more files and/or directories
*FileInfo gives file information for the specified object(s); this consists of the filename, the access permission, the filetype and datestamp or the load and execution addresses (in hexadecimal), and the length of the file in hexadecimal.
Under RISC OS 2, the information given varies between filing systems, as does the matching (or not) of wildcards.
*FileInfo current Current WR/ Text 15:54:37.40 04-Jan-1989 000007F
*Ex, *Info
*Info object_spec
object_spec - a valid (wildcarded) pathname specifying one or more files and/or directories
*Info gives file information for the specified object(s); this consists of the filename, the access permission, the filetype and datestamp or the load and execution addresses (in hexadecimal), and the length of the file.
If the file is dated, the date and time are displayed using the current Sys$DateFormat. If it is not dated, the load and exec addresses are displayed in hexadecimal.
*Info myfile myfile WR Text 15:54:37 04-Jan-1989 60 bytes
*Ex, *FileInfo
*LCat [directory]
directory - a valid pathname specifying a subdirectory of the current library
*LCat lists all the objects in the named library subdirectory. If no subdirectory is named, the objects in the current library are listed. *LCat is equivalent to *Cat %.
*Cat, *LEx
*LEx [directory]
directory - a valid pathname specifying a subdirectory of the current library
*LEx lists all the objects in the named library subdirectory together with their file information. If no subdirectory is named, the objects in the current library are listed. *LEx is the equivalent of *Ex %.
*Ex, *LCat
*Lib [directory]
directory - a valid pathname specifying a directory
*Lib selects a directory as the current library on a filing system. You can independently set libraries on each filing system.
If no other directory is named, the action taken will depend on which filing system is currently open: in ADFS the default is $.Library; under NetFS there is no default.
*Lib $.mylib
Sets the directory $.mylib to be the current library
*Configure Lib, *NoLib
*List [-File] filename [-TabExpand]
-File - may optionally precede filename; it has no effect
filename - a valid pathname specifying a file
-TabExpand - causes Tab characters (ASCII 9) to be expanded to 8 spaces
*List displays the contents of the named file using the configured DumpFormat. Control F might be displayed as '|F', for instance.
Each line is numbered. For a similar display without line numbers added, use *Type.
*List -file myfile -tabexpand
*Configure DumpFormat, *Dump, *Print, *Type
*Load filename [load_addr]
filename - a valid pathname specifying a file
load_addr - load address (in hexadecimal by default); this overrides the file's load address or any load address in the Alias$@LoadType variable associated with this file
*Load loads the named file at a load address specified (in hexadecimal by default).
The filename which is supplied with the *Load command is searched for in the directories listed in the system variable File$Path. By default, File$Path is set to ' '. This means that only the current directory is searched.
If no address is specified, the file's type (BASIC, Text etc) is looked for:
If the corresponding Alias$@LoadType variable does not exist then a suitable error is generated.
*Load myfile 9000
*Create, *Save
*NoDir
*NoDir unsets the current directory.
In RISC OS 2 this command is implemented by FileCore.
*Dir, *NoLib, *NoURD
*NoLib
*NoLib unsets the library directory.
In RISC OS 2 this command is implemented by FileCore.
*Lib, *NoDir, *NoURD
*NoURD
*NoURD unsets the User Root Directory (URD). This is shown as an '&' in pathnames.
In RISC OS 2 this command is implemented by FileCore.
*NoDir, *NoLib, *URD
*Opt 1 [[,]n]
n - 0 to 3
*Opt 1 sets the filing system message level (for operations involving loading, saving or creating a file) for the current filing system:
*Opt 1,0 - No filing system messages
*Opt 1,1 - Filename printed
*Opt 1,2 - Filename, hexadecimal addresses and length printed
*Opt 1,3 - Filename, and either datestamp and length, or hexadecimal load and exec addresses printed
*Opt 1 must be set separately for each filing system.
Under RISC OS 3 this command may not work correctly, depending on the operation (loading is generally worse) and filing system (NetFS is poor).
*Opt 4 [[,]n]
n - 0 to 3
*Opt 4 sets the boot option for the current filing system. On filing systems with several media (eg ADFS using several discs) the boot option is only set for the medium (disc) containing the currently selected directory.
*Opt 4,0 - No boot action
*Opt 4,1 - *Load boot file
*Opt 4,2 - *Run boot file
*Opt 4,3 - *Exec boot file
The boot file is usually named !Boot, although some filing systems may use different names; for example NetFS calls the file !ArmBoot (to avoid clashes with existing !Boot files that may contain code specific to BBC and Master series computers).
Note that a *Exec boot file will override the configured language setting. If you want such a boot file, and want to enter the desktop after executing it, the file should end with the command *Desktop; similarly for other languages.
*Opt 4,2 -
sets the boot option to *Run for the current filing system
*Configure Boot, *Configure NoBoot
*Print filename
filename - a valid pathname specifying a file
*Print displays the contents of the named file by sending each byte - whether it is a printable character or not - to the VDU. Unless the file is a simple text file, some unwanted screen effects may occur, since control characters are not filtered out.
*Print myfile
*Dump, *List, *Type
*Remove object_spec
object_spec - a valid (wildcarded) pathname specifying a file or an empty directory
*Remove erases the single named file or empty directory. No error message is given if the object does not exist; this allows a program to remove a file without having to trap that error. However, an error message is given if the object is a directory containing files.
You may not use wildcards in the last component of the pathname.
*Delete, *Wipe
*Rename object new_name
object - a valid pathname specifying a file or directory
new_name - a valid pathname specifying a file or directory
*Rename changes the name of an object, within the same storage unit. It can also be used for moving files from one directory to another, or moving directories within the directory tree.
Locked objects cannot be renamed (unlock them first by using the *Access command with the Lock option clear).
To move objects between discs or filing systems, use the *Copy command with the D(elete) option set.
*Rename fred jim
*Rename $.data.fred $.newdata.fred
Moves fred into directory newdata
*Access, *Copy
*Run filename [parameters]
filename - a valid pathname specifying a file
parameters - a Command Line tail (see the chapter entitled Program Environment for further details)
*Run loads and executes a file, optionally passing a list of parameters to it. The given pathname is searched for in the directories listed in the system variable Run$Path. If a matching object is a directory then it is ignored, unless it contains a !Run file.
The first file, or directory.!Run file that matches is used:
If the corresponding Alias$@RunType variable does not exist then a suitable error is generated.
By default, Run$Path is set to ',%.'. This means that the current directory is searched first, followed by the library. This default order is also used if Run$Path is not set.
*Run my_prog
*Run my_prog my_data
my_data is passed as a parameter to the program my_prog. The program can then use this filename to look up the data it needs.
*SetType
*Save filename start_addr end_addr [exec_addr [load_addr]]
or
*Save filename start_addr + length [exec_addr [load_addr]]
filename - a valid pathname specifying a file
start_addr - the address of the first byte to be saved
end_addr - the address of the byte after the last one to be saved
length - number of bytes to save
exec_addr - execution address (default is start_addr)
load_addr - load address (default is start_addr)
*Save copies the given area of memory to the named file. Start_addr is the address of the first byte to be saved; end_addr is the address of the byte after the last one to be saved. Length is the number of bytes to be saved; exec_addr is the execution address to be stored with the file (it defaults to start_addr). Load_addr is the reload address (which also defaults to start_addr).
The length and addresses are in hexadecimal by default.
*Save myprog 8000 + 3000
*Save myprog 8000 B000 9300 9000
*Load, *SetType
*SetType filename file_type
filename - a valid pathname specifying a file
file_type - a number (in hexadecimal by default) or text description of the file type to be set. The command *Show File$Type* displays a list of valid file types.
*SetType sets the file type of the named file. If the file does not have a date stamp, then it is stamped with the current time and date. Examples of file types are Palette, Font, Sprite and BASIC: for a list, see Table C: File types, or type *Show File$Type* at the command line.
Textual names take preference over numbers, so the sequence:
*Set File$Type_123 DFE *SetType filename DFE
will set the type of filename to &123, not &DFE - the string DFE is treated in the second command as a file type name, not number. To avoid such ambiguities we recommend you always precede a file type number by an indication of its base.
Build a small file containing a one-line command, set it to be a command type (&FFE), and run it from the Command Line; finally, view it from the desktop:
| *Build x | the file is given the name x |
| 1 *Echo Hello World | the line number is supplied by *Build |
| Esc | the Escape character terminates the file |
| *SetType x Command | *SetType x &FFE is an alternative |
| *Run x | the text is echoed on the screen |
The file has been ascribed the 'command file' type, and can be run by double-clicking on the file icon.
*Shut
None
*Shut closes all open files on all filing systems. The command may be useful to programmers to ensure that all files are closed if a program crashes without closing files.
You must not use this command within a program running in a multi-tasking environment such as the desktop, as it may close files being used by other programs.
*Bye, *Close, *ShutDown
Closes files, logs off file servers and parks hard disc heads
*ShutDown
None
*ShutDown closes all open files on all filing systems, and also logs off all NetFS file servers and parks hard disc heads in a safe state for switching off the computer.
You must not use this command within a program running in a multi-tasking environment such as the desktop, as it may close files being used by other programs.
*Bye, *Close, *Shut
Sends everything appearing on the screen to the specified file
*Spool [filename]
filename - a valid pathname specifying a file
*Spool opens the specified file for output; if a file of that name already exists, it is overwritten. All subsequent characters sent to the VDU drivers will be copied to the file, using OS_BPut. (If OS_BPut returns an error, the spool file is closed - thereby restoring the spool handle location - and the error is then returned from OS_WriteC.)
This copying continues until either a *Spool or a *SpoolOn command (with or without a file name) is issued, which then terminates the spooling.
If the pathname is omitted, the current spool file, if any, is closed, and characters are no longer sent to it. If the pathname is given, then the existing spool file is closed and the new one opened.
You can temporarily disable the spool file, without closing it, using OS_Byte 3.
*Spool %.Showdump
*Spool
*SpoolOn
BPutV, ByteV
Adds everything appearing on the screen to the end of an existing file
*SpoolOn [filename]
filename - a valid pathname specifying an existing file
*SpoolOn is similar to *Spool, except that it adds data to the end of an existing file. All subsequent characters sent to the VDU drivers will be copied to the end of the file, using OS_BPut. (If OS_BPut returns an error, the spool file is closed - thereby restoring the spool handle location - and the error is then returned from OS_WriteC.)
This copying continues until either a *SpoolOn or a *Spool command (with or without a filename) is issued, which then terminates the spooling.
If the filename is omitted, the current spool file, if any, is closed, and characters are no longer sent to it. If the filename is given, then the existing spool file is closed and the new one opened.
You can temporarily disable the spool file, without closing it, using OS_Byte 3.
*SpoolOn %.Showlist
*SpoolOn
*Spool
ByteV, BPutV
*Stamp filename
filename - a valid pathname specifying a file
*Stamp sets the date stamp on a file to the current time and date. If the file has not previously been date stamped, it is also given file type Data (&FFD).
*Stamp myfile
*Info, *SetType
*Type [-File] filename [-TabExpand]
-File - may optionally precede filename; it has no effect
filename - a valid pathname specifying a file
-TabExpand - causes Tab characters (ASCII 9) to be expanded to 8 spaces
*Type displays the contents of the named file using the configured DumpFormat. Control F might be displayed as '|F', for instance.
For a similar display with line numbers added, use *List.
*Type -File myfile -TabExpand
*Configure DumpFormat, *Dump, *List, *Print
*Up [levels]
levels - a positive number in the range 0 to 128 (in decimal by default)
*Up moves the current directory up the directory structure by the specified number of levels. If no number is given, the directory is moved up one level. *Up is equivalent to *Dir ^.
Note that while NetFS supports this command, some fileservers do not, so you may get a File 'up' not found error.
*Up 3
This is equivalent to *Dir ^.^.^, but note that the parent of $ is $, so you cannot go any further up the directory tree than this.
*Dir
*URD [directory]
directory - a valid pathname specifying a directory
*URD sets the User Root Directory (URD). This is shown as an '&' in pathnames.
If no directory is specified, the URD is set to the root directory.
In RISC OS 2 this command is implemented by FileCore.
*URD adfs::0.$.MyDir
*NoURD
*Wipe object_spec [[~]options]
object_spec - a valid (wildcarded) pathname specifying one or more files and/or directories
options - upper- or lower-case letters, optionally separated by spaces
A set of default options is read from the system variable Wipe$Options, which is set by the system as shown below. You can change these default preferences using the *Set command. You are recommended to type:
*Set Wipe$Options <Wipe$Options> extra_options
so you can see what the original options were before you added your extra ones. The default options are overruled by any given to the command.
To ensure an option is ON, include it in the list of options; to ensure it is OFF, precede the option by a '~' (eg: ~C~r to turn off the C and R options).
*Wipe deletes one or more objects that match the given wildcard specification.
If the Wipe$Options variable is unset then *Wipe behaves as if the variable were set to its default value.
*Wipe Games.* ~R
Deletes all files in the directory Games (but not any of its subdirectories).