FSEntry_GetBytes (changes)
Showing changes from revision #1 to #2:
Added | Removed | Changed
Get bytes from a buffered file
| Entry | |
|---|---|
| R1 | File handle used by your filing system/image filing system |
| R2 | Pointer to buffer |
| R3 | Number of bytes to read into buffer |
| R4 | File offset from which to get data |
| Exit | |
|---|---|
| - |
Use
This entry point is used by FileSwitch to request that you read a number of bytes from an open file, and place them in memory.
The file handle is guaranteed by FileSwitch not to be a directory, but not necessarily to have had read access granted at the time of the open – see the last case given below.
The memory address is not guaranteed to be of any particular alignment. You should if possible optimise your filing system’s transfers to word-aligned locations in particular, as FileSwitch’s and most clients do tend to be word-aligned. The speed of your transfer routine is vital to filing system performance.
The number of bytes to read, and the file offset from which to read data are guaranteed to be a multiple of the buffer size for this file. The file offset will be within the file’s extent.
This call is made by FileSwitch for several purposes:
- A client has called OS_BGet at a file offset where FileSwitch has no buffered data, and so FileSwitch needs to read the appropriate block of data into one of its buffers, from where data is returned to the client.
- A client has called OS_GBPB to read a whole number of the buffer size at a file offset that is a multiple of the buffer size. FileSwitch requests that the filing system transfer this data directly to the client’s memory. This is often the case where language libraries are being used for file access. If FileSwitch has any buffered data in the transfer range that has been modified but not yet flushed out to the filing system, then this data is copied to the client’s memory after the GetBytes call to the filing system.
- A client has called OS_GBPB to perform a more general read. FileSwitch will work out an appropriate set of data transfers. You may be called to fill FileSwitch’s buffers as needed and/or to transfer data directly to the client’s memory. You should make no assumptions about the exact number and sequence of such calls; as far as possible RISC OS tries to keep the calls in ascending order of file address, to increase efficiency by reducing seek times, and so on.
- A client has called OS_GBPB to perform a more general write. FileSwitch will work out an appropriate set of data transfers. You may be called to fill FileSwitch’s buffers as needed, so that the data at the start and/or end of the requested transfer can be put in the right place in FileSwitch’s buffers, ready for whole buffer transfer to the filing system as necessary.
Note that FileSwitch holds no buffered data immediately after a file has been opened.
Get bytes from an unbuffered file
| Entry | |
|---|---|
| R1 | File handle used by your filing system/image filing system |
| Exit | |
|---|---|
| R0 | byte read, C clear |
| or undefined, C set if attempting to read at end of file |
Use
This entry point is called by FileSwitch to get a single byte from an unbuffered file from the position given by the file’s sequential pointer. The sequential pointer must be incremented by one, unless the end of the file has been reached.
The file handle is guaranteed by FileSwitch not to be a directory and to have had read access granted at the time of the open.
Your filing system must not try to keep its own EOF-error-on-next-read flag – instead it must return with C set whenever the file’s sequential pointer is equal to its extent before a byte is read. It is FileSwitch’s responsibility to keep the EOF-error-on-next-read flag.
If your filing system does not support unbuffered GBPB directly, then FileSwitch will call this entry the necessary number of times to complete its client’s request, stopping if you return with the C flag set (EOF).
See also
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.