RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

FileSwitch


Introduction and Overview

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.

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

Data format

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.

Technical Details

Terminology

The following terms are used in the rest of this chapter:

  • a file is used to store data; it is distinct from a directory
  • a directory is used to contain files
  • an object may be either a file or a directory
  • a pathname gives the location of an object, and may include a filing system name, a special field, a media name (eg a disc name), directory name(s), and the name of the object itself; each of these parts of a pathname is known as an element of the pathname
  • a full pathname is a pathname that includes all relevant elements
  • a leafname is the last element of a full pathname.

Filenames

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:

. Separates directory specifications, eg $.fred
: Introduces a drive or disc specification, eg :0, :welcome. It also marks the end of a filing system name, eg adfs:
* Acts as a 'wildcard' to match zero or more characters, eg prog*
# Acts as a 'wildcard' to match any single character, eg $.ch##
$ is the name of the root directory of the disc
& is the user root directory (URD)
@ is the currently selected directory (CSD)
^ is the 'parent' directory
% is the currently selected library directory (CSL)
\ is the previously selected directory (PSD - available on FileCore-based filing systems, and any others that choose to do so)

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

Directories

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

Filing systems

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

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.

Current selections

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

System variables

Some of these values are available in system variables under RISC OS 3. These are:

Variable Meaning
FileSwitch$CurrentFilingSystem current filing system
FileSwitch$TemporaryFilingSystem temporary filing system
FileSwitch$fs$CSD CSD for filing system fs
FileSwitch$fs$PSD PSD for filing system fs
FileSwitch$fs$Lib library for filing system fs
FileSwitch$fs$URD URD for filing system fs
FileSwitch$SpecialField special field, evaluated as path is
processed

See also the Using FileSwitch$SpecialField with path variables.

File attributes

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.

Addresses / File types and date stamps

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:

Load and execution addresses

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.

File types and date stamps

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.

Additional information

Some filing systems may store additional information with each file. This is dependent on the implementation of the filing system.

Load-time and run-time system variables

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.

An example of LoadType

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

An example of RunType

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

Default settings

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

File$Path and Run$Path

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:

File$Path - for read operations
Run$Path - for execute operations

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.

Default values

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.

Specifying filing system names

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.

Resulting filenames

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.

Avoiding using File$Path and Run$Path

Certain SWI calls also allow you to specify alternative path strings, and to perform the operation with no path look-up at all.

Using other path variables

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.

Using FileSwitch$SpecialField with path variables

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.

System devices

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.

Filing system numbers

These are the currently allocated filing system numbers:

File system Number
None 0
RomFS 3
NetFS 5
ADFS 8
NetPrint 12
Null 13
Printer 14
Serial 15
Vdu 17
RawVdu 18
Kbd 19
RawKbd 20
DeskFS 21
Computer Concepts RomFS 22
RamFS 23
RISCiXFS 24
Streamer 25
SCSIFS 26
Digitiser 27
Scanner 28
MultiFS 29
NFS 33
CDFS 37
DOSFS 43 (This is not the DOSFS image filing system).
ResourceFS 46
PipeFS 47
DeviceFS 53
Parallel 54

Re-entrancy

FileSwitch can cope fully with recursive calls made to different streams - whether through the same or different entry points. For example:

  • Handle 254 is an output file on a disc that's been removed.
  • Handle 255 is a spool file.
  1. You call OS_BPut to put a byte to 254; this fills the buffer and causes a flush to the filing system.
  2. The filing system generates an UpCall to inform that the medium is missing.
  3. An UpCall handler prints a message asking the user to supply the medium.
  4. This goes through OS_BPut to 255, filling the buffer and causing a flush to the filing system.

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.

Interrupt code

You must not call the filing systems from interrupt code; FileCore based systems in particular give an error if you try to do so.

FileSwitch and the kernel

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.

Further calls

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.

Support of calls

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.

Protected files

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.

Service Calls


Service_StartUpFS
(Service Call &12)

Start up filing system

On entry

R1 = &12 (reason code)
R2 = filing system number (see Filing system numbers)

On exit

R1 preserved (never claim)
R2 preserved

Use

This is an old way to start up a filing system. It must not be claimed.


Service_FSRedeclare
(Service Call &40)

Filing system reinitialise

On entry

R1 = &40 (reason code)

On exit

R1 preserved to pass on (do not claim)

Use

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.


Service_CloseFile
(Service Call &68)

Close an object, and any children of that object

On entry

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)

On exit

R1, R2 preserved
R3 = number of files closed as a result of this service call (ie incremented appropriately)

Use

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.

SWI Calls


OS_Byte 127
(SWI &06)

Tells you whether the end of an open file has been reached

On entry

R0 = 127
R1 = file handle

On exit

R0 preserved
R1 indicates if end of file has been reached
R2 undefined

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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
Related SWIs

OS_Args 5, OS_Find

Related vectors

ByteV


OS_Byte 139
(SWI &06)

Selects file options (as used by *Opt)

On entry

R0 = 139
R1 = option number (first *Opt argument)
R2 = option value (second *Opt argument)

On exit

R0 preserved
R1, R2 undefined

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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.

Related SWIs

OS_FSControl 10

Related vectors

ByteV


OS_Byte 255
(SWI &06)

Reads the current auto-boot flag setting, or temporarily changes it

On entry

R0 = 255
R1 = 0 or new value
R2 = &FF or 0

On exit

R0 preserved
R1 = previous value
R2 corrupted

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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.

Related SWIs

OS_FSControl 10, OS_FSControl 15

Related vectors

ByteV


OS_File
(SWI &08)

Acts on whole files, either loading a file into memory, saving a file from memory, or reading or writing a file's attributes

On entry

R0 = reason code
Other registers depend on reason code

On exit

R0 corrupted
Other registers depend on reason code

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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.

Related SWIs

None

Related vectors

FileV


OS_File 0 and 10
(SWI &08)

Save a block of memory as a file

On entry

R0 = 0 or 10
R1 = pointer to non-wild-leaf filename
If R0 = 0

R2 = load address
R3 = execution address
If R0 = 10
R2 = file type (bits 0 - 11)
R4 = start address in memory of data (inclusive)
R5 = end address in memory of data (exclusive)

On exit

Registers preserved

Use

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.


OS_File 1, 2, 3, 4, 9, and 18
(SWI &08)

Write catalogue information for a named object

On entry

R0 = 1, 2, 3, 4, 9, or 18
R1 = pointer to (wildcarded) object name
If R0 = 1 or 2

R2 = load address
Else if R0 = 18
R2 = file type (bits 0 - 11)
If R0 = 1 or 3
R3 = execution address
If R0 = 1 or 4
R5 = object attributes

On exit

Registers preserved

Use

These calls write catalogue information for a named object to its catalogue entry, as shown below:

R0 Information written
1 Load address, execution address, object attributes
2 Load address
3 Execution address
4 Object attributes
9 Date/time stamp; file type is set to &FFD if not set already
18 File type, and date/time stamp if not set already

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.


OS_File 5, 13, 15 and 17
(SWI &08)

Read catalogue information for a named object

On entry

R0 = 5, 13, 15 or 17
R1 = pointer to (wildcarded) object name
If R0 = 13

R4 = pointer to control-character terminated comma separated path string
If R0 = 15
R4 = pointer to name of a path variable that contains a control-character terminated comma separated path string

On exit

R0 = object type
R1 preserved
R2 = load address
R3 = execution address
R4 = object length
R5 = object attributes
(R2 - R5 corrupted if object not found)

Use

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.


OS_File 6
(SWI &08)

Deletes a named object

On entry

R0 = 6
R1 = pointer to non-wildcarded object name

On exit

R0 = object type
R1 preserved
R2 = load address
R3 = execution address
R4 = object length
R5 = object attributes
(R2 - R5 corrupted if object not found)

Use

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:

  • it always sets bit 3 of R5 on return (the object is 'locked')
  • it returns the object's type as 2 (a directory) if it is successfully deleted.

The version supplied in RISC OS 3 does not behave like this.


OS_File 7 and 11
(SWI &08)

Creates an empty file

On entry

R0 = 7 or 11
R1 = pointer to non-wild-leaf file name
If R0 = 7

R2 = reload address
R3 = execution address
If R0 = 11
R2 = file type (bits 0 - 11)
R4 = start address (normally set to 0)
R5 = end address (normally set to length of file)

On exit

Registers preserved

Use

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.


OS_File 8
(SWI &08)

Creates a directory

On entry

R0 = 8
R1 = pointer to non-wild-leaf object name
R4 = number of entries (0 for default)

On exit

Registers preserved

Use

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.


OS_File 12, 14, 16 and 255
(SWI &08)

Load a named file

On entry

R0 = 12, 14, 16 or 255
R1 = pointer to (wildcarded) object name
If bottom byte of R3 is zero

R2 = address to load file at
R3 = 0 to load file at address given in R2, else bottom byte must be non-zero
If R0 = 12
R4 = pointer to control-character terminated comma separated path string
If R0 = 14
R4 = pointer to name of a path variable that contains a control-character terminated comma separated path string

On exit

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

Use

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.


OS_File 19
(SWI &08)

Generates an error message

On entry

R0 = 19
R1 = pointer to object name to report error for
R2 = object type (0, 1, 2 or &100)

On exit

R0 = pointer to error block
V flag set

Use

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.


OS_File 20, 21, 22 and 23
(SWI &08)

Read catalogue information for a named object

On entry

R0 = 20, 21, 22 or 23
R1 = pointer to (wildcarded) object name
If R0 = 21

R4 = pointer to control-character terminated comma separated path string
If R0 = 22
R4 = pointer to name of a path variable that contains a control-character terminated comma separated path string

On exit

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 '!')
Use

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.


OS_File 24
(SWI &08)

Reads the natural block size of a file

On entry

R0 = 24
R1 = pointer to file name

On exit

R2 = natural block size of the file in bytes

Use

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.


OS_Args
(SWI &09)

Reads or writes an open file's arguments, or returns the filing system type in use

On entry

R0 = reason code
R1 = file handle, or 0
R2 = attribute to write, or not used

On exit

R0 = filing system number (see Filing system numbers), or preserved
R1 preserved
R2 = attribute that was read, or preserved

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

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.

Related SWIs

None

Related vectors

ArgsV


OS_Args 0
(SWI &09)

Reads the temporary filing system number, or a file's sequential file pointer

On entry

R0 = 0
R1 = 0 or file handle

On exit

R0 = temporary filing system number (if R1 = 0 on entry), or preserved
R1 preserved
R2 = sequential file pointer (if R1 [NOT EQUAL] 0 on entry), or preserved

Use

This call reads the temporary filing system number (if R1 = 0 on entry), or a file's sequential file pointer (if R1 [NOT EQUAL] 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.


OS_Args 1
(SWI &09)

Writes an open file's sequential file pointer

On entry

R0 = 1
R1 = file handle
R2 = new sequential file pointer

On exit

R0 - R2 preserved

Use

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.


OS_Args 2
(SWI &09)

Reads an open file's extent

On entry

R0 = 2
R1 = file handle

On exit

R0, R1 preserved
R2 = extent of file

Use

This call reads an open file's extent. It indirects through ArgsV.


OS_Args 3
(SWI &09)

Writes an open file's extent

On entry

R0 = 3
R1 = file handle
R2 = new extent

On exit

R0 - R2 preserved

Use

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.


OS_Args 4
(SWI &09)

Reads an open file's allocated size

On entry

R0 = 4
R1 = file handle

On exit

R0, R1 preserved
R2 = allocated size of file

Use

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.


OS_Args 5
(SWI &09)

Reads an open file's end-of-file (EOF) status

On entry

R0 = 5
R1 = file handle

On exit

R0, R1 preserved
R2 = 0 if not EOF, else at EOF

Use

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.


OS_Args 6
(SWI &09)

Ensures an open file's size

On entry

R0 = 6
R1 = file handle
R2 = size to ensure

On exit

R0, R1 preserved
R2 = bytes reserved for file

Use

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.


OS_Args 7
(SWI &09)

Converts a file handle to a canonicalised name

On entry

R0 = 7
R1 = file handle
R2 = pointer to buffer to contain null terminated canonicalised name
R5 = size of buffer

On exit

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
Use

This call takes a file handle and returns its canonicalised name. This may be used as a two-pass process:

Pass 1

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)

Pass 2

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.


OS_Args 8
(SWI &09)

Used by an image filing system to inform of a change to an image stamp

On entry

R0 = 8
R1 = file handle
R2 = new image stamp

On exit

R0 - R2 preserved

Use

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.


OS_Args 254
(SWI &09)

Reads information on a file handle

On entry

R0 = 254
R1 = file handle (not necessarily allocated)

On exit

R0 = stream status word
R1 preserved
R2 = filing system information word

Use

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:

Bit Meaning when set
14 Image file busy
13 Data lost on this stream
12 Stream is critical (see below)
11 Stream is unallocated (see below)
10 Stream is unbuffered
9 Already read at EOF (EOF-error-on-next-read flag)
8 Object written to
7 Have write access to object
6 Have read access to object
5 Object is a directory
4 Unbuffered stream directly supports GBPB
3 Stream is interactive (ie prompting for input is appropriate)

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.


OS_Args 255
(SWI &09)

Ensure data has been written to a file, or all files on the temporary filing system

On entry

R0 = 255
R1 = file handle, or 0 to ensure all files on the temporary filing system

On exit

R0 - R2 preserved

Use

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 [NOT EQUAL] 0, in which case it is treated as a file handle).

This call indirects through ArgsV.


OS_BGet
(SWI &0A)

Reads a byte from an open file

On entry

R1 = file handle

On exit

R0 = byte read if C clear, undefined if C set
R1 preserved

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

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.

Related SWIs

OS_BPut, OS_GBPB

Related vectors

BGetV


OS_BPut
(SWI &0B)

Writes a byte to an open file

On entry

R0 = byte to be written
R1 = file handle

On exit

Registers preserved

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

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.

Related SWIs

OS_BGet, OS_GBPB

Related vectors

BPutV


OS_GBPB
(SWI &0C)

Reads or writes a group of bytes from or to an open file

On entry

R0 = reason code
Other registers depend on reason code

On exit

R0 preserved
Other registers depend on reason code

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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.

Related SWIs

OS_BGet, OS_BPut

Related vectors

GBPBV


OS_GBPB 1 and 2
(SWI &0C)

Write bytes to an open file

On entry

R0 = 1 or 2
R1 = file handle
R2 = start address of buffer in memory
R3 = number of bytes to write
If R0 = 1

R4 = sequential file pointer to use for start of block

On exit

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

Use

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.


OS_GBPB 3 and 4
(SWI &0C)

Read bytes from an open file

On entry

R0 = 3 or 4
R1 = file handle
R2 = start address of buffer in memory
R3 = number of bytes to read
If R0 = 3

R4 = sequential file pointer to use for start of block

On exit

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

Use

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.


OS_GBPB 5, 6 and 7
(SWI &0C)

Read information on a filing system

On entry

R0 = 5, 6 or 7
R2 = start address of buffer in memory

On exit

R0, R2 preserved
C flag corrupted

Use

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.

  • If R0 = 6, the call reads the name of the currently selected directory, and privilege status in relation to that directory. It is returned as:

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

  • If R0 = 7, the call reads the name of the library directory, and privilege status in relation to that directory. It is returned as:

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


OS_GBPB 8
(SWI &0C)

Reads entries from the current directory

On entry

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)

On exit

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

Use

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.


OS_GBPB 9, 10, 11 and 12
(SWI &0C)

Read entries and file information from a specified directory

On entry

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

On exit

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

Use

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:

Offset Contents
0 Load address
4 Execution address
8 Length
12 File attributes
16 Object type
20 System internal name - for internal use only
24 Time/Date (cs since 1/1/1900) - 0 if not stamped
29 Object name (null terminated)

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.


OS_Find
(SWI &0D)

Opens and closes files

On entry

R0 = reason code
Other registers depend on reason code

On exit

Depends on reason code

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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 [NOT EQUAL] 0 on entry then a file is opened for byte access. You can open files in the following ways:

  • open an existing file with read access only
  • create a new file with read/write access
  • open an existing file with read/write access

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.

Related SWIs

None

Related vectors

FindV


OS_Find 0
(SWI &0D)

Closes files

On entry

R0 = 0
R1 = file handle, or zero to close all files on current filing system

On exit

Registers preserved

Use

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.


OS_Find 64 to 255
(SWI &0D)

Open files

On entry

R0 = reason code
R1 = pointer to object name
R2 = optional pointer to path string or path variable

On exit

R0 = file handle, or 0 if object doesn't exist
R1 and R2 preserved

Use

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.


OS_FSControl
(SWI &29)

Controls the filing system manager and filing systems

On entry

R0 = reason code
Other registers depend on reason code

On exit

R0 preserved
Other registers depend on reason code

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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.

Related SWIs

None

Related vectors

FSCV


OS_FSControl 0
(SWI &29)

Set the current directory and (optionally) filing system

On entry

R0 = 0
R1 = pointer to (wildcarded) directory name

On exit

Registers preserved

Use

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.


OS_FSControl 1
(SWI &29)

Set the library directory

On entry

R0 = 1
R1 = pointer to (wildcarded) directory name

On exit

Registers preserved

Use

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.


OS_FSControl 2
(SWI &29)

Informs RISC OS and the current application that a new application is starting

On entry

R0 = 2
R1 = pointer to command tail to set
R2 = currently active object pointer to write
R3 = pointer to command name to set

On exit

Registers preserved - may not return

Use

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


OS_FSControl 4
(SWI &29)

Run a file

On entry

R0 = 4
R1 = pointer to (wildcarded) filename

On exit

Registers preserved

Use

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:

  • A file with no type is run as an absolute application, provided its load address is not below &8000. The environment string is set to the command line, and the current time is read into the environment time variable - see OS_GetEnv.
  • A file of type &FF8 (Absolute code) is run as an absolute application, loaded and entered at &8000. The environment string is set to the command line, and the current time is read into the environment time variable - see OS_GetEnv.
  • A file of type &FFC (Transient code modules) is loaded into the RMA and executed there. The environment string is set to the command line, and the current time is read into the environment time variable - see OS_GetEnv. Transient calls are nestable; when a transient returns to the filing system manager the RMA space is freed. The RMA space is also freed (on the reset service or filing system manager death) if the transient execution stopped abnormally, eg an exception occurred or RESET was pressed. See the chapter entitled Program Environment for details on writing transient utilities.
  • Otherwise, the corresponding Alias$@RunType system variable is looked up to determine how the file is run.

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.


OS_FSControl 5
(SWI &29)

Catalogue a directory

On entry

R0 = 5
R1 = pointer to (wildcarded) directory name

On exit

Registers preserved

Use

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.


OS_FSControl 6
(SWI &29)

Examine a directory

On entry

R0 = 6
R1 = pointer to (wildcarded) directory name

On exit

Registers preserved

Use

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.


OS_FSControl 7
(SWI &29)

Catalogue the library directory

On entry

R0 = 7
R1 = pointer to (wildcarded) directory name

On exit

Registers preserved

Use

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.


OS_FSControl 8
(SWI &29)

Examine the library directory

On entry

R0 = 8
R1 = pointer to (wildcarded) directory name

On exit

Registers preserved

Use

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.


OS_FSControl 9
(SWI &29)

Examine objects

On entry

R0 = 9
R1 = pointer to (wildcarded) pathname

On exit

R0 preserved

Use

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.


OS_FSControl 10
(SWI &29)

Sets filing system options

On entry

R0 = 10
R1 = option (0, 1 or 4)
R2 = parameter

On exit

Registers preserved

Use

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.


OS_FSControl 11
(SWI &29)

Set the temporary filing system from a named prefix

On entry

R0 = 11
R1 = pointer to string

On exit

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

Use

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.


OS_FSControl 12
(SWI &29)

Add a filing system

On entry

R0 = 12
R1 = module base address
R2 = offset of the filing system information block from the module base
R3 = private word pointer

On exit

R0 - R3 preserved

Use

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.


OS_FSControl 13
(SWI &29)

Check for the presence of a filing system

On entry

R0 = 13
R1 = filing system number (see Filing system numbers), or pointer to filing system name
R2 = R1 dependent

On exit

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

Use

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.


OS_FSControl 14
(SWI &29)

Filing system selection

On entry

R0 = 14
R1 = filing system number (see Filing system numbers), or pointer to filing system name

On exit

Registers preserved

Use

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.


OS_FSControl 15
(SWI &29)

Boot from a filing system

On entry

R0 = 15

On exit

R0 preserved

Use

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


OS_FSControl 16
(SWI &29)

Filing system removal

On entry

R0 = 16
R1 = pointer to filing system name

On exit

Registers preserved

Use

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


OS_FSControl 17
(SWI &29)

Add a secondary module

On entry

R0 = 17
R1 = pointer to filing system name
R2 = pointer to secondary system name
R3 = secondary module workspace pointer

On exit

Registers preserved

Use

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.


OS_FSControl 18
(SWI &29)

Decode file type into text

On entry

R0 = 18
R2 = file type (bits 0 - 11)

On exit

R0 preserved
R2 = first four characters of textual file type
R3 = second four characters of textual file type

Use

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.


OS_FSControl 19
(SWI &29)

Restore the current filing system

On entry

R0 = 19

On exit

R0 preserved

Use

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.


OS_FSControl 20
(SWI &29)

Read location of primary module for temporary filing system

On entry

R0 = 20

On exit

R0 preserved
R1 = primary module base address of temporary filing system
R2 = pointer to private word of temporary filing system

Use

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.


OS_FSControl 21
(SWI &29)

Return a filing system file handle

On entry

R0 = 21
R1 = file handle

On exit

R0 preserved
R1 = filing system file handle
R2 = filing system information word

Use

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.


OS_FSControl 22
(SWI &29)

Close all open files

On entry

R0 = 22

On exit

R0 preserved

Use

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.


OS_FSControl 23
(SWI &29)

Shutdown filing systems

On entry

R0 = 23

On exit

R0 preserved

Use

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:

  • logs off from all NetFS file servers
  • dismounts all discs on FileCore-based filing systems
  • parks the hard disc heads.

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.


OS_FSControl 24
(SWI &29)

Set the attributes of objects

On entry

R0 = 24
R1 = pointer to (wildcarded) pathname
R2 = pointer to attribute string

On exit

Registers preserved

Use

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.


OS_FSControl 25
(SWI &29)

Rename object

On entry

R0 = 25
R1 = pointer to current pathname
R2 = pointer to desired pathname

On exit

Registers preserved

Use

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.


OS_FSControl 26
(SWI &29)

Copy objects

On entry

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:

[R8] + 0 = information address
[R8] + 4 = information length

On exit

Registers preserved

Use

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:

Bit Meaning when set
14 Reads destination object information and applies tests before loading any of the source object.
13 Uses extra buffer specified using R8.
12 Copies only if source is newer than destination.
11 Copies directory structure(s) recursively, but not files.
10 Restamps datestamped objects - files are given the time at the start of this SWI, directories the time of their creation.
9 Doesn't copy over file attributes.
8 Allows printing during copy; printing is otherwise disabled. This option also disables any options that may cause characters to be written (bits 6, 4 and 3 are treated as cleared), and prevents FileSwitch from installing an UpCall handler to prompt for media changes.
7 Deletes the source after a successful copy (for renaming files across media).
6 Prompts you every time you might have to change media during the copy operation. In practise you are unlikely to need to use this option, as this SWI normally intercepts the UpCall vector and prompts you every time you do have to change media. (It only prompts if no earlier claimant of the vector has already tried to handle the UpCall.)
5 Uses application workspace as well as the relocatable module area.
4 Prints maximum information during copy.
3 Displays a prompt of the form 'Copy <object type> <source name> as <destination name> (Yes/No/Quiet/Abandon)?' for each object to be copied, and uses OS_Confirm to get a response. A separate confirm state is held for each level of recursion: Yes means to copy the object, No means not to copy the object, Quiet means to copy the object and to turn off confirmation at this level and subsequent ones (although if bit 1 is clear you will still be asked if you want to overwrite an existing file), and Abandon means not to copy the object and to return to the parent level. Escape abandons the entire copy without copying the object, and returns an error.
2 Copies only files with a time/date stamp falling between the start and end time/date specified in R4 - R7. (Unstamped files and directories will also be copied.) This check is made before any prompts or information is output.
1 Automatically unlocks, sets read and write permission, and overwrites an existing file. (If this bit is clear then the warning message 'File <destination name> already exists [and is locked]. Overwrite (Y/N) ? ' is given instead. If you answer Yes to this prompt then the file is similarly overwritten.)
0 Allows recursive copying down directories.

Buffers are considered for use in the following order, if they exist or their use is permitted:

  1. user buffer
  2. wimp free memory
  3. relocatable module area (RMA)
  4. application memory.

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.


OS_FSControl 27
(SWI &29)

Wipe objects

On entry

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)

On exit

Registers preserved

Use

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


OS_FSControl 28
(SWI &29)

Count objects

On entry

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)

On exit

R0, R1 preserved
R2 = total number of bytes of all files that were counted
R3 = number of files counted
R4 - R7 preserved

Use

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.


OS_FSControl 30
(SWI &29)

Read location of secondary module for temporary filing system

On entry

R0 = 30

On exit

R0 preserved
R1 = secondary module base address of temporary filing system
R2 = pointer to private word of temporary filing system

Use

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.


OS_FSControl 31
(SWI &29)

Converts a string giving a file type to a number

On entry

R0 = 31
R1 = pointer to control-character terminated filetype string

On exit

R0, R1 preserved
R2 = filetype

Use

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.


OS_FSControl 32
(SWI &29)

Outputs a list of object names and information

On entry

R0 = 32
R1 = pointer to wildcarded pathname

On exit

Registers preserved

Use

This call outputs a list of object names and information on them. The format is the same as for the *FileInfo command (see *FileInfo).


OS_FSControl 33
(SWI &29)

Converts a filing system number to a filing system name

On entry

R0 = 33
R1 = filing system number (see Filing system numbers)
R2 = pointer to buffer
R3 = length of buffer

On exit

Registers preserved

Use

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.


OS_FSControl 35
(SWI &29)

Add an image filing system

On entry

R0 = 35
R1 = module base address
R2 = offset of the image filing system information block from the module base
R3 = private word pointer

On exit

Registers preserved

Use

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.


OS_FSControl 36
(SWI &29)

Image filing system removal

On entry

R0 = 36
R1 = image filing system's file type

On exit

Registers preserved

Use

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.


OS_FSControl 37
(SWI &29)

Converts a pathname to a canonicalised name

On entry

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

On exit

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
Use

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:

    • 'a' may be resolved to 'adfs::HardDisc4.$.current.a' if the current directory is 'adfs::HardDisc4.$.current'.
    • 'a*' may be resolved to the same thing if 'a' exists and is the first match for 'a*', but, if there is no match for 'a*', then 'adfs::HardDisc4.$.current.a*' will be returned.
    • 'A' may be resolved to 'adfs::HardDisc4.$.current.A', which should be considered the same as 'adfs::HardDisc4.$.current.a'.

This may be used as a two-pass process:

Pass 1

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)

Pass 2

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.


OS_FSControl 38
(SWI &29)

Converts file information to an object's file type

On entry

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)

On exit

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 '!')
Use

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.


OS_FSControl 39
(SWI &29)

Sets the User Root Directory (URD)

On entry

R0 = 39
R1 = pointer to User Root Directory

On exit

--

Use

This call sets the User Root Directory, which is shown as an '&' in pathnames.

This call is not available in RISC OS 2.


OS_FSControl 40
(SWI &29)

Exchanges current and previous directories

On entry

R0 = 40

On exit

--

Use

This call swaps the current and previously selected directories.

This call is not available in RISC OS 2.


OS_FSControl 41
(SWI &29)

Returns the defect list for an image

On entry

R0 = 41
R1 = pointer to name of image (null terminated)
R2 = pointer to buffer
R5 = buffer length

On exit

R0 - R5 preserved

Use

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.


OS_FSControl 42
(SWI &29)

Maps out a defect from an image

On entry

R0 = 42
R1 = pointer to name of image (null terminated)
R2 = byte offset to start of defect

On exit

R0 - R2 preserved

Use

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.


OS_FSControl 43
(SWI &29)

Unsets the current directory

On entry

R0 = 43

On exit

--

Use

This call unsets the current directory on the temporary filing system.

This call is not available in RISC OS 2.


OS_FSControl 44
(SWI &29)

Unsets the User Root Directory (URD)

On entry

R0 = 44

On exit

--

Use

This call unsets the User Root Directory on the temporary filing system.

This call is not available in RISC OS 2.


OS_FSControl 45
(SWI &29)

Unsets the library directory (Lib)

On entry

R0 = 45

On exit

--

Use

This call unsets the library directory on the temporary filing system.

This call is not available in RISC OS 2.


OS_FSControl 46
(SWI &29)

Returns an image file's used space map

On entry

R0 = 46
R1 = pointer to name of image (null terminated)
R2 = pointer to buffer
R5 = buffer length

On exit

R0 - R5 preserved

Use

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.


OS_FSControl 47
(SWI &29)

Reads the boot option of the disc or image file that holds a specified object

On entry

R0 = 47
R1 = pointer to name of object (null terminated)

On exit

R0, R1 preserved
R2 = boot option

Use

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.


OS_FSControl 48
(SWI &29)

Writes the boot option of the disc or image file that holds a specified object

On entry

R0 = 48
R1 = pointer to name of object (null terminated)
R2 = new boot option

On exit

R0 - R2 preserved

Use

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.


OS_FSControl 49
(SWI &29)

Reads the free space on the disc or image file that holds a specified object

On entry

R0 = 49
R1 = pointer to name of object (null terminated)

On exit

R0 = free space
R1 = largest creatable object
R2 = disc size

Use

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.


OS_FSControl 50
(SWI &29)

Names the disc or image file that holds a specified object

On entry

R0 = 50
R1 = pointer to name of object (null terminated)
R2 = new name of disc

On exit

R0 - R2 preserved

Use

This call names the disc or image file that holds the specified object.

This call is not available in RISC OS 2.


OS_FSControl 51
(SWI &29)

Used by a handler of discs to request that an image stamp be updated

On entry

R0 = 51
R1 = pointer to name of object (null terminated)
R2 = sub-reason code:

0 stamp when updated
1 stamp now

On exit

R0 - R2 preserved

Use

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.


OS_FSControl 52
(SWI &29)

Finds the name and type of object that uses a particular offset within an image

On entry

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

On exit

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

Use

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.


OS_FSControl 53
(SWI &29)

Sets a specified directory to a given path without verification

On entry

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

On exit

Registers preserved

Use

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:

  • *Mount on ADFS may set the library to ':HardDisc4.$.Library'
  • *Logon on NetFS may set the URD to ':FileServer.&'.

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.


OS_FSControl 54
(SWI &29)

Reads the path of a specified directory

On entry

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

On exit

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

Use

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.

* Commands


*Access

Controls who can run, read from, write to and delete specific files

Syntax

*Access object_spec [attributes]

Parameters

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)

Use

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

Examples

*access myfile l

*access myfile wr/r

Related commands

*Ex, *FileInfo, *Info


*Append

Adds data to an existing file

Syntax

*Append filename

Parameters

filename - a valid pathname specifying an existing file

Use

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

Example

*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

Related commands

*Build


*Back

Exchanges current and previous directories

Syntax

*Back

Use

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

Related commands

*Dir


*Build

Opens a new file (or overwrites an existing one) and directs subsequent input to it

Syntax

*Build filename

Parameters

filename - a valid pathname specifying a file

Use

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

Example

*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

Related commands

*Append


*Cat

Lists all the objects in a directory

Syntax

*Cat [directory]

Parameters

directory - a valid pathname specifying a directory

Use

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

Examples
*. 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
Related commands

*Ex, *FileInfo, *Info, *LCat and *LEx


*CDir

Creates a directory

Syntax

*CDir directory [size_in_entries]

Parameters

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)

Use

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

Examples
*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
Related commands

*Cat


*Close

Closes all open files on the current filing system

Syntax

*Close

Parameters

None

Use

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

Related commands

*Bye, *Shut, *Shutdown


*Configure Boot

Sets the configured boot action so that a power on, reset or Ctrl Break runs a boot file

Syntax

*Configure Boot

Parameters

None

Use

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

Related commands

*Configure NoBoot, *FX 255


*Configure DumpFormat

Sets the configured format used by the *Dump, *List and *Type commands

Syntax

*Configure DumpFormat n

Parameters

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.

Use

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

Example

*Configure DumpFormat 2

Related commands

*Dump, *List, *Type


*Configure FileSystem

Sets the configured filing system to be used at power on or hard reset

Syntax

*Configure FileSystem fs_name | fs_number

Parameters

fs_name - a filing system name (ADFS, Net or Ram)

fs_number - a filing system number (see Filing system numbers)

Use

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

Example

*Configure FileSystem Net


*Configure NoBoot

Sets the configured boot action so that a Shift power on, Shift reset or Shift Break runs a boot file

Syntax

*Configure NoBoot

Parameters

None

Use

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

Related commands

*Configure Boot, *FX 255, *Rename


*Configure Truncate

Sets the configured value for whether or not filenames are truncated when too long

Syntax

*Configure Truncate On|Off

Parameters

On - long filenames are truncated

Off - long filenames are not truncated

Use

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

Example

*Configure Truncate On

Related commands

None


*Copy

Copies files and directories

Syntax

*Copy source_spec destination_spec [[~]options]

Parameters

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

  • A(ccess) - Force destination access to same as source.
    Default ON.

    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.

  • C(onfirm) - Prompt for confirmation of each copy.
    Default ON.

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

  • D(elete) - Delete the source object after copy.
    Default OFF.

    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.

  • F(orce) - Force overwriting of existing objects.
    Default OFF.

    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.

  • L(ook) - Look at destination before loading source file.
    Default OFF.

    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.

  • N(ewer) - Copy only if source is more recent than destination.
    Default OFF.

    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.

  • P(rompt) - Prompt for the disc to be changed as needed in copy.
    Default OFF.

    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.

  • Q(uick) - Use application workspace as a buffer.
    Default OFF.

    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.

  • R(ecurse) - Copy subdirectories and contents.
    Default OFF.

    This is useful when copying several levels of directory, since it avoids the need to copy each of the directories one by one.

  • S(tamp) - Restamp date-stamped files after copying.
    Default OFF.

    Useful for recording when the particular copy was made.

  • (s)T(ructure) - Copy only the directory structure.
    Default OFF.

    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.

  • V(erbose) - Print information on each object copied.
    Default ON.

    This gives full textual commentary on the copy operation.

Use

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

Examples

*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'.

Related commands

*Access, *Delete, *Rename, *Wipe, and the system variable Copy$Options.


*Count

Adds up the size of data held in file objects, and the number of objects

Syntax

*Count object_spec [[~]options]

Parameters

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

  • C(onfirm) - Prompt for confirmation of each count.
    Default OFF.
  • R(ecurse) - Count subdirectories and contents.
    Default ON.
  • V(erbose) - Print information on each file counted.
    Default OFF.

This gives information on each file counted, rather than just printing the subtotal counted in directories.

Use

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

Example

*Count $ r~cv
Counts all files on disc, giving full information on each file object

Related commands

*Ex, *FileInfo, *Info, and the system variable Count$Options


*Create

Reserves space for a new file

Syntax

*Create filename [length [exec_addr [load_addr>]]]

Parameters

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)

Use

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

Examples

*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

Related commands

*Load, *Save


*Defect

Reports what object contains a defect, or (if none) marks the defective part of the disc so it will no longer be used

Syntax

*Defect disc_spec disc_addr

Parameters

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'

Use

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

Example

*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

Related commands

*CheckMap, *Verify


*Delete

Erases a single file or empty directory

Syntax

*Delete object_spec

Parameters

object_spec - a valid (wildcarded) pathname specifying a file or an empty directory

Use

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

Examples

*Delete $.dir*.myfile
Uses wildcards

*Delete myfile
Deletes myfile from the current directory

Related commands

*Remove, *Wipe


*Dir

Selects a directory

Syntax

*Dir [directory]

Parameters

directory - a valid pathname specifying a directory

Use

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

Examples

*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

Related commands

*Back, *CDir


*Dump

Displays the contents of a file, in hexadecimal and ASCII codes

Syntax

*Dump filename [file_offset [start_addr]]

Parameters

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

Use

*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:

  • whether the top bit of a byte is stripped first
  • how bytes are displayed if their top bits are set.

If a file is time/date stamped, it is treated as having a load address of zero.

Example

*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

Related commands

*Configure DumpFormat, *List, *Type


*EnumDir

Creates a file of object leafnames

Syntax

*EnumDir directory output_file [pattern]

Parameters

directory - a valid pathname specifying a directory

output_file - a valid pathname specifying a file

pattern - a wildcard specification for matching against

Use

*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 @.

Examples

*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

Related commands

*Cat, *LCat


*Ex

Lists file information within a directory

Syntax

*Ex [directory]

Parameters

directory - a valid pathname specifying a directory

Use

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

Example

*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

Related commands

*FileInfo, *Info


*Exec

Executes a command file

Syntax

*Exec [filename]

Parameters

filename - a valid pathname specifying a file

Use

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

Example

*Exec !Boot
uses the file !Boot as though its contents have been typed in from the keyboard

Related commands

*Obey

Related SWIs

OS_Byte 198

Related vectors

None


*FileInfo

Gives full file information about specified objects

Syntax

*FileInfo object_spec

Parameters

object_spec - a valid (wildcarded) pathname specifying one or more files and/or directories

Use

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

Example

*FileInfo current
Current    WR/    Text      15:54:37.40 04-Jan-1989 000007F

Related commands

*Ex, *Info


*Info

Gives file information about specified objects

Syntax

*Info object_spec

Parameters

object_spec - a valid (wildcarded) pathname specifying one or more files and/or directories

Use

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

Example

*Info myfile
myfile     WR  Text      15:54:37 04-Jan-1989   60  bytes

Related commands

*Ex, *FileInfo


*LCat

Displays objects in a library

Syntax

*LCat [directory]

Parameters

directory - a valid pathname specifying a subdirectory of the current library

Use

*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 %.

Related commands

*Cat, *LEx


*LEx

Displays file information for a library

Syntax

*LEx [directory]

Parameters

directory - a valid pathname specifying a subdirectory of the current library

Use

*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 %.

Related commands

*Ex, *LCat


*Lib

Selects a directory as a library

Syntax

*Lib [directory]

Parameters

directory - a valid pathname specifying a directory

Use

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

Example

*Lib $.mylib
Sets the directory $.mylib to be the current library

Related commands

*Configure Lib, *NoLib


*List

Displays the contents of a file, numbering each line

Syntax

*List [-File] filename [-TabExpand]

Parameters

-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

Use

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

Example

*List -file myfile -tabexpand

Related commands

*Configure DumpFormat, *Dump, *Print, *Type


*Load

Loads the named file (usually a program file)

Syntax

*Load filename [load_addr]

Parameters

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

Use

*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 file has no file type, it is loaded at its own load address.
  • If the file does have a file type, the corresponding Alias$@LoadType variable is looked up to determine how the file is to be loaded. A BASIC file has a file type of &FFB, so the variable Alias$@LoadType_FFB is looked up, and so on. You are unlikely to need to change the default values of these variables.

If the corresponding Alias$@LoadType variable does not exist then a suitable error is generated.

Example

*Load myfile 9000

Related commands

*Create, *Save


*NoDir

Unsets the current directory

Syntax

*NoDir

Use

*NoDir unsets the current directory.

In RISC OS 2 this command is implemented by FileCore.

Related commands

*Dir, *NoLib, *NoURD


*NoLib

Unsets the library directory.

Syntax

*NoLib

Use

*NoLib unsets the library directory.

In RISC OS 2 this command is implemented by FileCore.

Related commands

*Lib, *NoDir, *NoURD


*NoURD

Unsets the User Root Directory (URD).

Syntax

*NoURD

Use

*NoURD unsets the User Root Directory (URD). This is shown as an '&' in pathnames.

In RISC OS 2 this command is implemented by FileCore.

Related commands

*NoDir, *NoLib, *URD


*Opt 1

*Opt 1 controls filing system messages

Syntax

*Opt 1 [[,]n]

Parameters

n - 0 to 3

Use

*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

*Opt 4 sets the filing system boot option

Syntax

*Opt 4 [[,]n]

Parameters

n - 0 to 3

Use

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

Example

*Opt 4,2 -
sets the boot option to *Run for the current filing system

Related commands

*Configure Boot, *Configure NoBoot


*Print

Displays the contents of a file as raw text on the screen

Syntax

*Print filename

Parameters

filename - a valid pathname specifying a file

Use

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

Example

*Print myfile

Related commands

*Dump, *List, *Type


*Remove

Erases a single file or empty directory

Syntax

*Remove object_spec

Parameters

object_spec - a valid (wildcarded) pathname specifying a file or an empty directory

Use

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

Related commands

*Delete, *Wipe


*Rename

Changes the name of an object

Syntax

*Rename object new_name

Parameters

object - a valid pathname specifying a file or directory

new_name - a valid pathname specifying a file or directory

Use

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

Examples

*Rename fred jim

*Rename $.data.fred $.newdata.fred
Moves fred into directory newdata

Related commands

*Access, *Copy


*Run

Loads and executes a file

Syntax

*Run filename [parameters]

Parameters

filename - a valid pathname specifying a file

parameters - a Command Line tail (see the chapter entitled Program Environment for further details)

Use

*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 file has no file type, it is loaded at its own load address, and execution commences at its execution address.
  • If the file has type &FF8 (Absolute code) it is loaded and run at &8000
  • Otherwise the corresponding Alias$@RunType variable is looked up to determine how the file is to be run. A BASIC file has a file type of &FFB, so the variable Alias$@RunType_FFB is looked up, and so on. You are unlikely to need to change the default values of these variables.

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.

Examples

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

Related commands

*SetType


*Save

Copies an area of memory to a file

Syntax

*Save filename start_addr end_addr [exec_addr [load_addr]]

or

*Save filename start_addr + length [exec_addr [load_addr]]

Parameters

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)

Use

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

Examples

*Save myprog 8000 + 3000

*Save myprog 8000 B000 9300 9000

Related commands

*Load, *SetType


*SetType

Sets the file type of a file

Syntax

*SetType filename file_type

Parameters

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.

Use

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

Example

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

Closes all open files

Syntax

*Shut

Parameters

None

Use

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

Related commands

*Bye, *Close, *ShutDown


*ShutDown

Closes files, logs off file servers and parks hard disc heads

Syntax

*ShutDown

Parameters

None

Use

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

Related commands

*Bye, *Close, *Shut


*Spool

Sends everything appearing on the screen to the specified file

Syntax

*Spool [filename]

Parameters

filename - a valid pathname specifying a file

Use

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

Example

*Spool %.Showdump

*Spool

Related commands

*SpoolOn

Related SWIs

OS_Byte 3, OS_Byte 199, OS_File, OS_BPut

Related vectors

BPutV, ByteV


*SpoolOn

Adds everything appearing on the screen to the end of an existing file

Syntax

*SpoolOn [filename]

Parameters

filename - a valid pathname specifying an existing file

Use

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

Example

*SpoolOn %.Showlist

*SpoolOn

Related commands

*Spool

Related SWIs

OS_Byte 3, OS_Byte 199, OS_File, OS_BPut

Related vectors

ByteV, BPutV


*Stamp

Date stamps a file

Syntax

*Stamp filename

Parameters

filename - a valid pathname specifying a file

Use

*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).

Example

*Stamp myfile

Related commands

*Info, *SetType


*Type

Displays the contents of a file

Syntax

*Type [-File] filename [-TabExpand]

Parameters

-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

Use

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

Example

*Type -File myfile -TabExpand

Related commands

*Configure DumpFormat, *Dump, *List, *Print


*Up

Moves the current directory up the directory structure

Syntax

*Up [levels]

Parameters

levels - a positive number in the range 0 to 128 (in decimal by default)

Use

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

Example

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

Related commands

*Dir


*URD

Sets the User Root Directory (URD)

Syntax

*URD [directory]

Parameters

directory - a valid pathname specifying a directory

Use

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

Example

*URD adfs::0.$.MyDir

Related commands

*NoURD


*Wipe

Deletes one or more objects.

Syntax

*Wipe object_spec [[~]options]

Parameters

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

  • C(onfirm) - Prompt for confirmation of each deletion.
    Default ON.
  • F(orce) - Force deletion of locked objects.
    Default OFF.
  • R(ecurse) - Delete subdirectories and contents.
    Default OFF.
  • V(erbose) - Print information on each object deleted.
    Default ON.
Use

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

Example

*Wipe Games.* ~R
Deletes all files in the directory Games (but not any of its subdirectories).

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015