Using the ROMFS file system (high-level API fs.h)

The API is defined in the header file sysroot-*-kos/include/kos/fs.h from the KasperskyOS SDK.

This API is intended for working with the ROMFS file system that is managed by the KasperskyOS kernel or by the system program FSUsr (but not VFS).

The fs.h API is obsolete, therefore you are advised to use the romfs.h API instead.

Information about API functions is provided in the table below.

The libkos library also provides a low-level API for using the ROMFS file system. The low-level API should be used only if the high-level API does not have sufficient capabilities.

Selecting a file system endpoint

A process can use the ROMFS file system endpoint provided by the kernel or by the system program FSUsr. For more details, refer to Using the ROMFS file system (low-level API fs_api.h).

Opening a file

To open a file, call the KosOpenFile() function while specifying the file name via the fname parameter.

Reading data from a file

To read data from a file, use the KosLoadFileToBuf(), KosReadFileRaw() or KosReadFile() function.

The KosLoadFileToBuf() uses the input parameter path to get the pointer to the file name, therefore you do not need to open the file in advance. This function creates a buffer and copies the entire file to it. After it is used, this buffer must be flushed by calling the KosMemFree() function from the alloc.h API.

The KosReadFileRaw() function reads a file starting from the defined offset relative to the beginning of the file. The KosReadFile() function reads a file starting at the current location of the cursor. Immediately after a file is opened, the cursor has a zero offset relative to the beginning of the file. The KosReadFileRaw() function ignores and preserves the file position indicator and does not change it. A repeated call of the KosReadFileRaw() function with the same parameters will read from the same part of the file. The KosReadFile() function takes into account the file position indicator and offsets it to the end of the file according to the size of the read data. A repeated call of the KosReadFile() function with the same parameters will then read from a different part of the file that follows the part that was read by the previous call.

To get the position of the cursor (offset of the cursor relative to the beginning of the file), you must call the KosGetFilePos() function.

To set the necessary position of the cursor, you must call the KosSeekFile() function. The base for setting the cursor position can be the beginning of the file, the current position of the cursor, or the end of the file. If the beginning of the file is used as the base, you must specify a positive offset. If the current position of the cursor is used as the base, you must specify a positive or negative offset. If the end of the file is used as the base, you must specify a negative offset. The necessary cursor position must not go beyond the file boundaries.

Getting the file size

To get the file size, call the KosGetFileSize() function.

Closing a file

To close the file, call the KosCloseFile() function.

Information about API functions

fs.h functions

Function	Information about the function
KosOpenFile()	Purpose Opens a file. Parameters [in] fname – pointer to the file name. Returned values If successful, the function returns the file ID, otherwise it returns RTL_NULL.
KosReadFileRaw()	Purpose Reads data from a file, starting from the defined offset. Parameters [in] file – file ID. [out] buffer – pointer to the data read buffer. [in] size – size of the buffer defined via the buffer parameter (in bytes). [in] offset – offset (relative to the beginning of the file) from which reading should start, in bytes. Returned values If successful, the function returns the size (bytes) of the read data, otherwise it returns 0.
KosReadFile()	Purpose Reads data from a file, starting with the current position of the cursor. Parameters [in] file – file ID. [out] buffer – pointer to the data read buffer. [in] size – size of the buffer defined via the buffer parameter (in bytes). Returned values If successful, the function returns the size (bytes) of the read data, otherwise it returns 0.
KosGetFileSize()	Purpose Gets the size of a file. Parameters [in] file – file ID. Returned values If successful, the function returns the file size (in bytes). If it returns 0, this indicates that either the file size is zero or an error occurred.
KosGetFilePos()	Purpose Gets the position of the cursor. Parameters [in] file – file ID. Returned values Cursor position (offset of the cursor relative to the beginning of the file), in bytes.
KosSeekFile()	Purpose Sets the position of the cursor. Parameters [in] file – file ID. [in] offset – offset of the cursor relative to the base defined in the origin parameter (in bytes). [in] origin – base for setting the cursor position: beginning of the file (SEEK_SET), current position of the cursor (SEEK_CUR), and end of the file (SEEK_END). Returned values If successful, the function returns the cursor position (offset of the cursor relative to the beginning of the file), in bytes. If it returns 0, this indicates that either a zero offset was set for the cursor or there was an error in which the cursor position defined by the offset and origin parameters is outside of the file boundaries. If this type of error occurs, the current position of the cursor is not changed.
KosCloseFile()	Purpose Closes a file. Parameters [in] file – file ID. Returned values N/A
KosLoadFileToBuf()	Purpose Creates a buffer and copies the file to it. Parameters [in] path – pointer to the file name. [out] fileBuf – pointer to the address of the buffer containing data from the file. [out] fileSize – pointer to the file size (in bytes). Returned values If successful, the function returns rcOk, otherwise it returns an error code.

Page top