FSEntry_Open (changes)
Showing changes from revision #0 to #1:
Added | Removed | Changed
Open a file
| Entry | |
|---|---|
| R0 | Reason code |
| R1 | Pointer to filename |
| R2 | FileSwitch handle for the file |
| R3 | Pointer to special field if present, otherwise 0 |
| Exit | |
|---|---|
| R0 | File information word (not the same as the filing system information word) |
| R1 | Your filing system’s handle for the file (0 if not found) |
| R2 | Buffer size for FileSwitch to use (0 if file unbuffered, else must be a power of 2 between 64 and 1024) |
| R3 | File extent (buffered files only) |
| R4 | Space currently allocated to file (buffered files only: must be a multiple of buffer size) |
Use
FileSwitch calls this entry point to open a file for read or write, and to create it if necessary.
On entry, R3 contains the handle that FileSwitch will use for the file if your filing system successfully opens it. This is a small integer (typically going downwards from 255), but must be treated as a 32-bit word for future compatibility. Your filing system may want to make a note of it when the file is opened, in case it needs to refer to files by their FileSwitch handles (for example, it must close all open files on a *Dismount). It is the FileSwitch handle that the user sees.
On exit, your filing system must return a 32-bit file handle that it uses internally to FileSwitch. FileSwitch will then use this file handle for any further calls to your filing system. You may use any value, apart from a handle of 0 which means that no file is open.
The value returned in R2 is the natural block size of the file; for disc oriented filing systems, this should be the same as the natural sector size. FileSwitch – when calling the filing system – will tend to use multiple of this value, aligned on a boundary which is also a multiple of this value.
If your memory allocation fails, this is not an error, and you should indicate it to FileSwitch by setting R1 to 0 on exit.
The reason code given in R0 has the following meaning:
| Value | Meaning |
|---|---|
| 0 | Open for read |
| 1 | Create and open for update (only used by RISC OS 2) |
| 2 | Open for update |
For both reason codes 0 and 2 FileSwitch will already have checked that the object exists (unless you have overridden this by setting bit 28 of the filing system information word) and, for reason code 2 only, that it is not a directory. These reason codes must not alter a file’s datestamp.
If a directory is opened for reading, then bytes will not be requested from it. The use of this is for compatibility with existing programs which use this as a method of testing the existence of an object.
For reason code 1 FileSwitch will already have checked that the leafname is not wildcarded, and that the object is not an existing directory. Your filing system should return an extent of zero. If the file already exists you should return an allocated space the same as that of the file; otherwise you should return a sensible default that allows space for the file to grow. Your filing system should also give a new file a filetype of &FFD (Data), datestamp it, and give it sensible access attributes (WR/ is recommended).
The file information word returned in R0 uses the following bits:
| Bit | Meaning if set |
|---|---|
| 31 | Write permitted to this file |
| 30 | Read permitted from this file |
| 29 | Object is a directory |
| 28 | Unbuffered OS_GBPB supported (stream-type devices only) |
| 27 | Stream is interactive |
All other bits are reserved and should be set to 0.
An interactive stream is one on which prompting for input is appropriate, such as kbd:.
See also
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.