The Linkset Data File System (LDFS) is a specification for storing data in linkset data. By using linkset data, 64 kilobytes of emulated filesystem storage is available to the Mark 1 and compatible external storage automatically through the LDFS driver written in native LSL.
LDFS supports files up to 8192 characters stored in up to 8 directory depths. Additionally, a maximum of 128 files and 128 directories may be stored in each directory. These limitations are due to limited memory available in LSL while navigating the directory structure.
Each LDFS filesystem can store up to 65536 bytes of data. Each file in the filesystem takes 6-13 bytes of memory, plus data, depending on its name. Each directory takes 7-14 bytes of memory depending on its name, except the root directory, which takes 9-19 bytes depending on the disk label.
The LDFS driver will automatically allocate one RAM memory bank on boot for internal use.
Software should not make these calls directly. Interacting with the LDFS driver directly does not allow you to perform operations on external storage media. Software should use BIOS_DISK_OP instead, which supports all of the same operations.
Most system calls accept either a [path] or [path/file.ext] parameter. Canonically, paths and files are formatted as: /PARENT/CHILD/file.ext, using "forward" slashes, a leading slash, uppercase directories, and lowercase filenames.
For input parameters, the LDFS driver accepts paths using either slashes (/) or backslashes (\), ignores capitalization, and does not require a leading slash.
The LDFS initializes with a root directory only. If SCOPE is installed, the installer will create a basic directory structure on the system unit's LDFS.
Only one LDFS driver is allowed in each linkset. As a result, there is no need to distinguish between different LDFS drivers or drives when making system calls.
Directory names may be between 1 and 8 characters, inclusive, and may only contain the following characters: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ !#$%&'()-@^_`{}~
File names may be between 1 and 8 characters, inclusive, followed by a period (.), then between 1 and 3 characters, inclusive, for the extension.
These naming formats deviate from common modern 8.3 filename specifications because filenames must have a name, a period, and an extension; neither can be blank. Additionally, non-printable control characters are not supported.
Note that there is no limitation on the ordering of valid characters in directory and file names; therefore, it is possible to have a directory name consisting of a single space, or to accidentally include extra spaces before or after names.
Each file is stored with a 6-bit field with the following flags:
1: stub file2: read-only file4: hidden8: symlink16: 4096-byte size (used to calculate file contents size)32: (reserved)Attributes are defined as integers and all attributes are stored combined as a single integer. When sending attributes to the LDFS driver, you must combine flags using LSL's | operator (or +). When receiving attributes from the LDFS driver, you may check them against flags using LSL's & operator. For example, to check if the file is read-only, you could use if ([attributes] & 2).
Stub files are files that define an executable stub through the SCI. Stub files may use any extension, but only certain extensions enable certain features in the SCI. For more information, refer to the SCI's documentation.
Stub files may only be created using the WS (Write Stub/Symlink) command and may only be read using the RS (Read Stub/Symlink) and XX (Execute) commands. Stub files may be moved/copied and deleted using the normal MF (Move File) and DF (Delete File) commands. When interacting with files using the WA (Write Attributes) operation, the stub file attribute bit cannot be changed.
The content of a stub file is the name of the LSL script it refers to.
Read-only files cannot be modified using the DF (Delete File), MD (Move Directory), MF (Move File, unless the [force] flag is set), and WF (Write File), operations. To perform any of these operations, you must first use the WA (Write Attributes) operation to clear the read-only flag in the file's [attributes].
Hidden files and directories are omitted from the results of the RD (Read Directory) operation unless the [include_hidden] parameter is set to a value that returns hidden files.
Symlinks (symbolic links) are directories and files that force the LDFS driver to route to another directory or file in the filesystem while navigating the directory structure. Symlinks are similar to shortcuts except that directories may also act as symlinks to other directories.
Symlinks may only be created using the WS (Write Stub/Symlink) command and may only be read directly using the RS (Read Stub/Symlink) command. Symlinks may be moved/copied and deleted using the normal MD (Move Directory), MF (Move File), DD (Delete Directory), and DF (Delete File) commands, which will only affect the symlink, not its target. When interacting with files using the WA (Write Attributes) operation, and when changing directory attributes using the WD (Write Directory) operation, the symlink attribute bit cannot be changed.
The content of a symlink is a [path] or [path/file.ext] parameter to another directory or file. Symlink directories may only point to directories, and symlink files may only point to files. The contents of a symlink file are not validated until runtime, so symlinks can be created to non-existent directories and files and/or may eventually become orphaned if the targeted directory or file is deleted after the symlink is created.
The LDFS driver incorporates no native operation ordering. If you attempt to perform a blocking operation while one is already in progress, the LDFS driver will return error 12 (op in progress). It is the software's responsibility to detect this, wait, and attempt to perform the operation again.
The MD (Move Directory), MF (Move File), RD (Read Directory), RF (Read File), WA (Write Attributes), WD (Write Directory), and WF (Write File) operations are "blocking" operations; that is, while they are being processed, the LDFS driver cannot accept any other blocking operations and any attempt to do so will return error 12 (op in progress).
Software may check the blocking state of the LDFS driver by checking the first character of the root directory's linkset data entry. This can be checked from any LSL script in the same linkset as follows:
integer is_blocked()
{
return (integer)llGetSubString(llList2String(llLinksetDataFindKeys("^0000.$", 0, 1), 0), 0, 0) & 1;
}
LDFS defines this character as a 3-bit integer bitfield. Currently, only the least significant bit (1) is used, but other bits in this field may be used later, so software should check only to see if the 1 bit is set, as shown in the above example.
This character is synchronously updated while the LDFS driver performs blocking operations, though there may still be a very small delay between checking this character and when another script sends a blocking command, so software should still monitor for errors.
The remainder of the contents of the root directory linkset data entry is subject to change in future LDFS revisions, so should not be read directly.
Software should not monitor the state of this linkset data value using the
linkset_dataLSL event. If this event is defined in an LSL script, it must run every time a file is modified on the system and may use enough LSL memory to crash the script.
| System Call | Description |
|---|---|
| BIOS_DISK_LDFS_BLOCK | Sets or clears the LDFS driver blocking state. |
| BIOS_DISK_LDFS_OP | Performs an LDFS local disk operation. |
| System Call | Description |
|---|---|
| BIOS_DISK_LDFS_RESP | Status response to BIOS_DISK_LDFS_OP. |