API is defined in the header file sysroot-*-kos/include/coresrv/fs/fs_api.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_api.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 high-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. In the first case, the process can access the ROMFS file system that is put into the kernel space and is managed by the kernel, respectively. In the second case, the process can access the ROMFS file system that is put into the user space and is managed by the FSUsr program. The FSUsr program lets you mount any ROMFS image that may be significantly larger than the ROMFS image in the kernel space. An image of the kernel-managed ROMFS file system is created during the solution build and it is automatically loaded into the kernel space and mounted when the solution is started.
To enable the use of a ROMFS file system that is put into the user space, you must include the FSUsr program in your KasperskyOS-based solution. (To check whether the FSUsr program is included in your KasperskyOS SDK, verify that the sysroot-*-kos/bin/fsusr executable file is available.) The libkos library serves as the client library of the FSUsr program and automatically creates an IPC channel to the FSUsr program process. There should be only one FSUsr program process.
The specific parent process determines which of the two ROMFS file system endpoints is used by default (for details, see Managing processes (high-level API task.h)).
To get information indicating which of the two ROMFS file system endpoints is used, call the KosTaskGetSelfFSBackend() function from the task.h API.
To change the ROMFS file system endpoint, call the KnFsChangeBackend() function. If the endpoint provided by the kernel is used by default, the first call of this function with the value KosTaskFSBackendUsr in the fsBackend parameter also dynamically creates an IPC channel to the process of the FSUsr program. If the endpoint provided by the FSUsr program is used by default, the IPC channel to the process of this program is created dynamically when the libkos library is initialized.
You can change the ROMFS file system endpoint multiple times during the lifetime of the process.
To mount the ROMFS image that is loaded in the user space, call the KnFsChange() function. This function can be applied only when using the ROMFS endpoint provided by the FSUsr program. If a ROMFS image has already been mounted, the KnFsChange() function unmounts it and mounts the new one. The virtual memory region for the ROMFS image must be reserved and committed via one call of the KnVmAllocate() function from the vmm_api.h API. After calling the KnFsChange() function, this region can be freed. The physical memory occupied by the ROMFS image will be freed after the image is unmounted. Otherwise it would remain occupied until the corresponding virtual memory is freed.
To unmount the ROMFS image without mounting a new one, call the KnFsChange() function with the RTL_NULL and 0 values in the base and size parameters, respectively.
By default, a child process may use the ROMFS file system that resides in the user space and is mounted by the parent process (for details, see Managing processes (high-level API task.h)).
The FSUsr program process may have multiple clients at the same time. In this case, you must ensure ROMFS image mount synchronization so that one process does not replace an image if it is needed by another process. You can also use a solution security policy, which lets you prohibit calls of the interface method of the FSUsr program to replace the ROMFS image.
Getting file system information
To get the size of a file system, call the KnFsGetFsSize() function.
To find out the number of files in a file system, call the KnFsCountFiles() function.
To get the names of files in a file system, use the KnFsGetFileInfo() function. To enumerate all files, you must increment the value in the index parameter beginning with zero until you receive the rcInvalidArgument error. In addition to the file name, this function lets you get the unique ID of a file that may be used, for example, to identify the structure containing the file metadata (similar to use of the inode structure in UNIX-like operating systems).
Opening a file
To open a file, call the KnFsOpen() function while specifying the file name via the name parameter.
Reading data from a file
To read data from a file, use the KnFsRead() function. Data is read in fixed-size blocks. The data block size (in bytes) corresponds to the value of the FileSectorSize constant defined in the sysroot-*-kos/include/kl/core/FS.idl file from the KasperskyOS SDK. To read all data from a file, you must increment the value in the sectorNumber parameter beginning with zero until the total size of the read data is equal to the file size, or until the size of the read data received via the read parameter is less than the size of a data block.
Receiving information about a file
To get the file size, call the KnFsGetFileSize() function.
To get the unique ID of a file, call the KnFsGetFileId() function.
Closing a file
To close the file, call the KnFsClose() function.
Information about API functions
fs_api.h functions
Function |
Information about the function |
|---|---|
|
Purpose Opens a file. Parameters
Returned values If successful, the function returns |
|
Purpose Closes a file. Parameters
Returned values If successful, the function returns |
|
Purpose Reads data from a file. Parameters
Returned values If successful, the function returns |
|
Purpose Gets the size of a file. Parameters
Returned values If successful, the function returns |
|
Purpose Gets the unique ID of a file. Parameters
Returned values If successful, the function returns |
|
Purpose Gets the number of files in the file system. Parameters
Returned values If successful, the function returns |
|
Purpose Gets the name and unique ID of a file based on the file index. Parameters
Returned values If successful, the function returns If the value in the |
|
Purpose Changes the ROMFS image residing in the user space. Parameters
Returned values If successful, the function returns |
|
Purpose Gets the size of the ROMFS file system. Parameters
Returned values If successful, the function returns |
|
Purpose Defines whether the ROMFS file system for a calling process is supported by the kernel or by the Parameters
Returned values If successful, the function returns |