FSEntry_PutBytes (changes)

Showing changes from revision #0 to #1: Added | Removed | Changed

Put bytes to a buffered file

Use

This entry point is called by FileSwitch to request that you take a number of bytes, and place them in the file at the specified file offset.

The file handle is guaranteed by FileSwitch not to be a directory, and to have had write access granted at the time of the open.

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 write, and the file offset at which to write data are guaranteed to be a multiple of the buffer size for this file. The final write will be within the file’s extent, so it will not need extending.

This call is made by FileSwitch for several purposes:

• A client has called OS_GBPB to write 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 from 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 discarded (as it has obviously been invalidated by this operation).

• A client has called OS_BGet/OS_BPut/OS_GBPB at a file offset where FileSwitch has no buffered data, and the current buffer held by FileSwitch has been modified and so must be written to the filing system. (The current FileSwitch implementation does not maintain multiple buffers on each file. It is likely that this will remain the case, as individual filing systems have better knowledge about how to do disc-caching, and intelligent readahead and writebehind for given devices.)

• 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 empty FileSwitch’s buffers as needed and/or to transfer data directly from 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.

Note that FileSwitch holds no buffered data immediately after a file has been opened.

Put bytes to an unbuffered file

Use

This entry point is called by FileSwitch to request that you put a single byte to an unbuffered file at the position given by the file’s sequential file pointer. You must advance the sequential pointer by one. If the sequential pointer is equal to the file extent when this call is made, you must increase the allocated space of the file by at least one byte to accommodate the data – although it will be more efficient to increase the allocated space in larger chunks (256 bytes/1k is common).

The file handle is guaranteed by FileSwitch not to be a directory, and to have had write access granted at the time of the open.

If your filing system does not support FSEntry_GBPB, then FileSwitch will call this entry the necessary number of times to complete its client’s request.

See also

• FS Information Block
• OS_FSControl