Использование файловой системы ROMFS (низкоуровневый API fs_api.h)

API определен в заголовочном файле sysroot-*-kos/include/coresrv/fs/fs_api.h из состава KasperskyOS SDK.

API предназначен для работы с файловой системой ROMFS, управляемой ядром KasperskyOS или системной программой FSUsr (но не VFS).

API fs_api.h является устаревшим, поэтому вместо него рекомендуется использовать API romfs.h.

Сведения о функциях API приведены в таблице ниже.

Библиотека libkos также предоставляет высокоуровневый API для использования файловой системы ROMFS. Низкоуровневый API следует использовать, если недостаточно возможностей высокоуровневого API.

Выбор службы файловой системы

Процесс может использовать службу файловой системы ROMFS, предоставляемую ядром или системной программой FSUsr. В первом случае процессу доступна файловая система ROMFS, помещенная в пространство ядра и соответственно управляемая ядром. Во втором случае процессу доступна файловая система ROMFS, помещенная в пользовательское пространство и управляемая программой FSUsr. Программа FSUsr позволяет смонтировать произвольный образ ROMFS, который может быть существенно большего размера, чем образ ROMFS в пространстве ядра. Образ управляемой ядром файловой системы ROMFS создается при сборке решения и при запуске решения автоматически загружается в пространство ядра и монтируется.

Чтобы можно было использовать файловую систему ROMFS, помещенную в пользовательское пространство, нужно включить программу FSUsr в решение на базе KasperskyOS. (Чтобы проверить, поставляется ли программа FSUsr в составе KasperskyOS SDK, нужно убедиться в наличии исполняемого файла sysroot-*-kos/bin/fsusr.) В качестве клиентской библиотеки программы FSUsr выступает библиотека libkos, которая автоматически создает IPC-канал к процессу программы FSUsr. Должен существовать только один процесс программы FSUsr.

Какая из двух служб файловой системы ROMFS используется по умолчанию, зависит от родительского процесса (подробнее см. "Управление процессами (высокоуровневый API task.h)").

Чтобы получить сведения о том, какая из двух служб файловой системы ROMFS используется, нужно вызвать функцию KosTaskGetSelfFSBackend() из API task.h.

Чтобы сменить службу файловой системы ROMFS, нужно вызвать функцию KnFsChangeBackend(). Если по умолчанию используется служба, предоставляемая ядром, то первый вызов этой функции со значение KosTaskFSBackendUsr в параметре fsBackend также выполняет динамическое создание IPC-канала до процесса программы FSUsr. Если по умолчанию используется служба, предоставляемая программой FSUsr, то IPC-канал до процесса этой программы создается динамически при инициализации библиотеки libkos.

На протяжении времени жизни процесса можно неоднократно менять службу файловой системы ROMFS.

Чтобы смонтировать образ ROMFS, загруженный в пользовательское пространство, нужно вызвать функцию KnFsChange(). Эту функцию можно применять, если только используется служба ROMFS, предоставляемая программой FSUsr. Если образ ROMFS уже смонтирован, функция KnFsChange() размонтирует его и монтирует новый. Регион виртуальной памяти для образа ROMFS должен быть зарезервирован с фиксацией посредством одного вызова функции KnVmAllocate() из API vmm_api.h. После вызова функции KnFsChange() этот регион можно освободить. При этом физическая память, занятая образом ROMFS, будет освобождена после размонтирования образа, иначе останется занятой до освобождения соответствующей виртуальной памяти.

Чтобы размонтировать образ ROMFS без монтирования нового, нужно вызвать функцию KnFsChange() со значениями RTL_NULL и 0 в параметрах base и size соответственно.

Дочерний процесс может по умолчанию использовать файловую системы ROMFS, которая помещена в пользовательское пространство и смонтирована родительским процессом (подробнее см. "Управление процессами (высокоуровневый API task.h)").

Процесс программы FSUsr может иметь одновременно несколько клиентов. В таком случае нужно обеспечить синхронизацию монтирования образа ROMFS, чтобы один процесс не заменил образ, если он требуется другому процессу. При этом можно использовать политику безопасности решения, которая позволяет запретить вызывать интерфейсный метод программы FSUsr для замены образа ROMFS.

Получение сведений о файловой системе

Чтобы получить размер файловой системы, нужно вызвать функцию KnFsGetFsSize().

Чтобы получить число файлов в файловой системе, нужно вызвать функцию KnFsCountFiles().

Чтобы получить имена файлов в файловой системе, нужно использовать функцию KnFsGetFileInfo(). Для перечисления всех файлов нужно инкрементировать значение в параметре index, начиная с нуля, до получения ошибки rcInvalidArgument. Помимо имени файла эта функция позволяет получить уникальный идентификатор файла, который может быть использован, например, для идентификации структуры с метаданными о файле (подобно применению структуры inode в UNIX-подобных операционных системах).

Открытие файла

Чтобы открыть файл, нужно вызвать функцию KnFsOpen(), указав имя файла через параметр name.

Чтение данных из файла

Чтобы выполнить чтение данных из файла, нужно использовать функцию KnFsRead(). Чтение выполняется блоками данных фиксированного размера. Размер блока данных (в байтах) соответствует значению константы FileSectorSize, определенной в файле sysroot-*-kos/include/kl/core/FS.idl из состава KasperskyOS SDK. Для считывания всех данных из файла нужно инкрементировать значение в параметре sectorNumber, начиная с нуля, пока суммарный размер считанных данных не станет равным размеру файла, или размер считанных данных, получаемый через параметр read, не станет меньше размера блока.

Получение сведений о файле

Чтобы получить размер файла, нужно вызвать функцию KnFsGetFileSize().

Чтобы получить уникальный идентификатор файла, нужно вызвать функцию KnFsGetFileId().

Закрытие файла

Чтобы закрыть файл, нужно вызвать функцию KnFsClose().

Сведения о функциях API

Функции fs_api.h

Функция	Сведения о функции
KnFsOpen()	Назначение Открывает файл. Параметры [in] name – указатель на имя файла. [out] handle – указатель на дескриптор файла. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsClose()	Назначение Закрывает файл. Параметры [in] handle – дескриптор файла. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsRead()	Назначение Читает данные из файла. Параметры [in] handle – дескриптор файла. [in] sectorNumber – номер блока данных. Нумерация начинается с нуля. [out] read – указатель на размер считанных данных в байтах. [out] data – указатель на буфер для считанных данных. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsGetFileSize()	Назначение Позволяет получить размер файла. Параметры [in] handle – дескриптор файла. [out] size – указатель на размер файла в байтах. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsGetFileId()	Назначение Позволяет получить уникальный идентификатор файла. Параметры [in] handle – дескриптор файла. [out] id – указатель на уникальный идентификатор файла. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsCountFiles()	Назначение Позволяет получить число файлов в файловой системе. Параметры [out] count – указатель на число файлов в файловой системе. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsGetFileInfo()	Назначение Позволяет получить имя и уникальный идентификатор файла по индексу файла. Параметры [in] index – индекс файла. Нумерация начинается с нуля. [out] buf – указатель на буфер для имени файла. [in] buflen – размер буфера для имени файла, в байтах. Максимальный размер имени файла (в байтах), включая терминирующий ноль, соответствует значению константы ROMFS_NAME_MAX, определенной в заголовочном файле sysroot-*-kos/include/rtl/romfs_info.h из состава KasperskyOS SDK. [optional,out] id – указатель на уникальный идентификатор файла или RTL_NULL, если не требуется получать этот идентификатор. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Если значение в параметре index равно числу файлов в файловой системе или превышает это число, возвращает rcInvalidArgument.
KnFsChange()	Назначение Меняет образ ROMFS, размещенный в пользовательском пространстве. Параметры [in,optional] base – указатель на регион виртуальной памяти с образом ROMFS или RTL_NULL, если нужно размонтировать используемый образ ROMFS без монтирования нового. Базовый адрес региона виртуальной памяти с образом ROMFS должен быть выровнен на границу страницы памяти. [in,optional] size – размер региона виртуальной памяти с образом ROMFS, кратный размеру страницы памяти, в байтах, или 0, если нужно размонтировать используемый образ ROMFS без монтирования нового. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsGetFsSize()	Назначение Позволяет получить размер файловой системы ROMFS. Параметры [out] fsSize – указатель на размер файловой системы в байтах. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFsChangeBackend()	Назначение Задает, как осуществляется поддержка файловой системы ROMFS для вызывающего процесса: ядром или системной программой FSUsr. Параметры [in] fsBackend – значение, которое задает, как осуществляется поддержка файловой системы ROMFS (KosTaskFSBackendKernel – ядром, KosTaskFSBackendUsr – системной программой FSUsr). Тип параметра определен в заголовочном файле sysroot-*-kos/include/kos/task.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало