The sys::fs service is in charge of operations related to the filesystems.
sys::fsservice- Behaviour
- Methods
0x0001IS_FS_MOUNTED0x0002ENUM_FS0x0003FS_METADATA0x0004FS_MOUNT0x0005FS_UNMOUNT0x0006FS_WATCH0x0007FS_UNWATCH0x1000ITEM_EXISTS0x1001FEID_TO_SPLIT0x1002ITEM_METADATA0x2000RENAME_ITEM0x2001MOVE_ITEM0x2002DELETE_ITEM0x3000CREATE_DIRECTORY0x3001READ_DIRECTORY0x4000OPEN_FILE0x4001CLOSE_FILE0x4002READ_FILE0x4002WRITE_FILE0x5000CREATE_SYMLINK0x5001UPDATE_SYMLINK0x5002READ_SYMLINK0xA000WATCH_ITEM0xA001UNWATCH0xF000FORMAT
- Notifications
A single filesystem operation request from a client process up to the hardware device traverses:
- Client
sys::fsservice- filesystem interface (only if the filesystem is not supported natively)
- storage driver service (only if a filesystem interface is used, or if the storage device requires a specific driver)
- Hardware storage device
The response then goes up through all layers. Note that in all cases, the sys::hw don't need to be contacted, thanks to direct driver access.
In the best scenario, which is for natively supported filesystems on storage devices that don't require a dedicated driver, direct storage access is possible, reducing the traversal to:
- Client
sys::fsservice- Hardware storage device
The following filesystems are natively supported, meaning they don't require a filesystem interface to work properly:
- Btrfs
- Ext2 / Ext3 / Ext4
- NTFS
- FAT12 / FAT16 / FAT32
- exFAT
It is possible to use other filesystems that the natively supported ones, using filesystem interfaces.
This, however, creates a higher latency as direct access and operations are not permitted anymore. The typical sequence of operations becomes:
- The client calls the
sys::fsservice to perform a given operation - The operation is transmitted to the related filesystem interface...
- ...which in turns contact the
sys::hwservice... - ...which itself transmits the operation to the underlying storage driver
The information then goes up:
- From the driver to
sys::hw - Then to the filesystem interface which translates it
- Then back to the
sys::fsservice - And finally to the client
The sys::fs serviec is responsible for detecting filesystems. It performs this by contacting the sys::hw service to enumerate and access the different storage devices, as well as being notified when a storage device is connected, disconnected or changes.
Filesystems are detected using a variety of methods. If all fail (which is, if the filesystem is not one that is natively supported), filesystem interfaces are used one by one to find one that can handle the said filesystem, using their IS_VALID_PARTITION method.
Each partition then gets an identifier, the filesystem unique identifier (FSID), which is consistent across reboots but different between computers to avoid collection of informations from the FSID alone.
Check if a given filesystem is mounted.
Required permission: fs.filesystems.mounted
Arguments:
- FSID (8 bytes)
Return value:
0x01if the filesystem is currently mounted,0x00else
Errors:
None
Enumerate all available filesystems.
Required permission: fs.filesystems.list
Arguments:
None
Return value:
- Delimited list of FSID (8 bytes)
Errors:
None
Get informations on a filesystem.
Required permission: fs.filesystems.metadata
Arguments:
- FSID (8 bytes)
Return value:
- Mount timestamp (8 bytes)
- Mount path FEID (8 bytes)
- Option of the mounted volume file's FEID (1 + 8 bytes)
- Filesystem metadata
Errors:
0x3000: The requested filesystem is currently not mounted
Mount an existing filesystem. If no mount path is provided, the filesystem will be mounted under the /mnt directory.
New filesystems are automatically detected when storage devices are connected.
Required permission: fs.filesystems.mount
Arguments:
- FSID (8 bytes)
- Option of the mount path as a delimited string
Return value:
None
Errors:
0x3000: Unknown FSID (8 bytes)0x3001: This filesystem is already mounted
Unmount a mounted filesystem.
Required permission fs.filesystems.unmount
Arguments:
- FSID (8 bytes)
Return value:
None
Errors:
0x3000: Unknown FSID (8 bytes)0x3001: This filesystem is current not mounted
Subscribe to FS_CHANGED notifications when a filesystem is mounted or unmounted.
Required permission: fs.filesystems.watch
Arguments:
None
Return value:
None
Errors:
None
Unsubscribe from FS_WATCH.
Required permission: None
Arguments:
None
Return value:
None
Errors:
None
Check if a given item exists.
Required permissions:
fs.path.existsto check any item typefs.feid.existsto check only FEID
Arguments:
- FSID (40 bytes)
- Filesystem path
- Item type byte (1 byte) to check if the item exists and is of a specific type -
0to accept all types
Return value:
- Item type byte (1 byte)
Errors:
0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted
Convert a FEID to the corresponding split path.
Required permissions:
fs.path.exists
Arguments:
Return value:
Errors:
0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: The provided FEID was not found in the filesystem
Get the metadata of a given item.
Required permissions:
fs.items.metadatato get symbolic links' metadata
Arguments:
- FSID (40 bytes)
- Filesystem path
Return value:
Errors:
0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: The provided path was not found
Rename an existing item.
Required permissions:
fs.items.move
Arguments:
- FSID (40 bytes)
- Filesystem path
- New filename
Errors:
0x3000: Invalid filename provided0x3001: Invalid FSID provided0x3002: Requested filesystem is currently not mounted0x3003: The provided path was not foud
Move an existing item.
fs.items.move
Arguments:
- FSID (40 bytes)
- Filesystem path
- New parent directory
- Optional new filename
Errors:
0x1000: Invalid filename provided0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: The provided path was not found0x3003: Target directory was not found0x4000: Target directory's maximum capacity has been reached0x4001: Maximum nested items number has been reached0x4002: Maximum path length has been reached0x4003: Item cannot be moved for unspecified reasons0x4FFF: Unspecified filesystem error
Delete an item.
Required permissions:
fs.items.remove.trashto send items to the trashfs.items.removeto delete items permanently
Arguments:
- FSID (40 bytes)
- Filesystem path
- Deletion mode (1 byte):
0x01to send the item to the user's trash,0x02to delete it permanently
Return value:
None
Errors:
0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: Item was not found0x3003: Cannot remove a non-empty directory0x4FFF: Unspecified filesystem error
Create a directory.
Required permissions:
fs.items.create
Arguments:
- FSID (40 bytes)
- Filesystem path of the parent directory
- New item's filename
Return value:
None
Errors:
0x1000: Invalid filename provided0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: Parent directory was not found0x4000: Directory's maximum capacity has been reached0x4001: Maximum nested items number has been reached0x4002: Maximum path length has been reached0x4FFF: Unspecified filesystem error
List all entries in a directory.
Required permissions:
fs.dir.readfs.dir.read.hiddento also list hidden items
Arguments:
- FSID (40 bytes)
- Filesystem path
- Hidden flag match boolean (1 byte): match hidden items
Return value:
Errors:
0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: Directory was not found0x4FFF: Unspecified filesystem error
Open a file with the provided options.
Opening a file with read access will prevent writes and removal while the file is open. Opening a file with write access will prevent read, writes and removal while the file is open.
Note that read and write access can be enabled together.
Required permissions:
fs.items.createif the file must be createdfs.items.readfor read accessfs.items.writefor write access
Arguments:
- FSID (40 bytes)
- Enumeration (1 + ? bytes)
- Type ID
0x00: Existing filesystem path to open - Type ID
0x01: Existing filesystem path of the parent directory
- Type ID
- Enable read access (1 byte)
- Enable write access (1 byte)
Return value:
- Opened file ID (8 bytes)
Errors:
0x3000: Invalid FSID provided0x3001: Invalid parent directory provided0x3002: Requested filesystem is not currently mounted0x3003: Provided file path was not found0x3004: Provided directory path was not found0x4000: File is already opened0x4001: Directory's maximum capacity has been reached0x4002: Maximum nested items number has been reached0x4003: Maximum path length has been reached0x4FFF: Unspecified filesystem error
Close a file.
Removes all locks on the opened file.
Arguments:
- Opened file ID (8 bytes)
Errors:
0x3000: Invalid opened file ID provided
Read an open file.
Required permissions:
None (implicitly given by the initial OPEN_FILE call)
Arguments:
- Opened file ID (8 bytes)
- Offset to read from (8 bytes)
- Length to read (8 bytes)
- Writable buffer pointer
Errors:
0x3000: Invalid opened file ID provided0x3001: File is not opened in read mode0x3002: Provided offset is out-of-range0x3003: Provided offset + length is out-of-range0x4FFF: Unspecified filesystem error
Write an open file.
File will grow if needed.
Required permissions:
None (implicitly given by the initial OPEN_FILE call)
Arguments:
- Opened file ID (8 bytes)
- Offset to write from (8 bytes)
- Length to write (8 bytes)
- Readable buffer pointer
- Truncate boolean (1 byte): truncate the file's length to the end of the written data
Errors:
0x3000: Invalid opened file ID provided0x3001: File is not opened in write mode0x3002: Provided offset is out-of-range0x4000: Filesystem capacity exceeded0x4001: Maximum file size exceeded0x4FFF: Unspecified filesystem error
Create a symbolic link.
Required permissions:
fs.symlinks.create
Arguments:
- FSID (40 bytes)
- Filesystem path of the parent directory
- New item's filename
- Symlink's target FSID (8 bytes)
- Symlink's target path (always a split path for other filesystems)
Return value:
None
Errors:
0x3000: Invalid filename provided0x3001: Invalid FSID provided0x3002: Requested filesystem is currently not mounted0x3003: Parent directory was not found0x3004: Cannot create symbolic links to cross-filesystem items0x3005: Cannot create symbolic links to non-existing items0x4000: Directory's maximum capacity has been reached0x4001: Maximum nested items number has been reached0x4002: Maximum path length has been reached0x4003: Storage's capacity exceeded0x4FFF: Unspecified filesystem error
Create a symbolic link.
Required permissions:
fs.symlinks.update
Arguments:
- FSID (40 bytes)
- Symlink's path
- Symlink's target FSID (8 bytes)
- Symlink's target path
Return value:
None
Errors:
0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: Provided path was not found0x3003: Cannot crate symbolic links to cross-filesystem items0x3004: Cannot crate symbolic links to non-existing items0x4FFF: Unspecified filesystem error
Read a symbolic link's target.
Required permissions:
fs.symlinks.read
Arguments:
Return value:
- Symlink's target FSID (8 bytes)
- Symlink's target path
Errors:
0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x3002: Provided path was not found0x4000: Symbolic link is cyclic
Watch an item for changes on its metadata or content. Any change will trigger a ITEM_CHANGED notification.
Required permission:
fs.items.metadata
Arguments:
Errors:
0x3000: Invalid FSID provided0x3001: Provided path was not found
Stop watching a content watched with WATCH_ITEM.
Arguments:
- Generated watch identifier (8 bytes)
Errors:
0x3000: Provided watch identifier was not found
Asynchronously format the partition to get an empty filesystem.
Required permissions:
fs.filesystems.format
Arguments:
Return value:
- Generated task identifier (8 bytes)
Error codes:
0x1000: Invalid sector size provided0x3000: Invalid FSID provided0x3001: Requested filesystem is currently not mounted0x4000: Unspecified filesystem error
Sent to a client which subscribed through FS_WATCH each time a filesystem is mounted or unmounted.
Datafield:
Notification sent to clients watching an item through the WATCH_ITEM method.
Datafield:
- FSID (8 bytes)
- FEID (8 bytes)
- Event code (1 byte):
0x01: item's metadata changed (timestamps excluded)0x02: item was moved0x03: item was deleted0x04: item was locked (only for the parent directory if case of a recursive lock)0x05: item was unlocked (only for the parent directory if case of a recursive lock)