FileSystem API

The filesystem api provides structures, functions and variables for interacting with the virtual file systems.

You can’t access files outside the virtual filesystem. If you try to do so, the Lua runtime crashes.

Virtual File System

FicsIt-Networks implements it’s own virtual filesystem for UNIX like experience using the FileSystem.

The file system consists of nodes. Such a node can be a File, a Folder or something else. Each nodes is able to have child nodes and might be able to get opened with a file stream. A folder also delivers an abstract interface for adding and removing nodes. A Device implements lookup functions for searching for nodes in the filesystem structure. Such a device can be a temporary filesystem (tmpfs) which exists only in memory and which will get purged on a system reboot, or f.e. a disk filesystem (drives) which store the nodes on the real virtual filesystem in a folder. You can then mount such a device to a location in the root filesystem tree so when you now access a path, the filesystem looks first for the device and uses then the remaining path to get the node data from the device.

There is also a DriveNode which simply holds a reference to a drive so you can access a drive via the filesystem. You can use then the mount function to mount the Drive of a DriveNode to the given location in the filesystem tree.

Because you need at least one drive mounted to even be able to access any node, we provide the initFileSystem function which you can call only once in a system session. This functions will then mount the DevDevice to the given location.

The DevDevice is a sepcial Device which holds all the DeviceNodes representing Device attached to the computer session, like hard drives, tempfs and the serial I/O.

Functions

bool initFileSystem(string path)

Trys to mount the system DevDevice to the given location.

The DevDevice is special Device holding DeviceNodes for all filesystems added to the system. (like TmpFS and drives). It is unmountable as well as getting mounted a seccond time.

Parameters
Name Type Description

path

string

path to the mountpoint were the dev device should get mounted to

Return Values
Name Type Description

bool

bool

returns if it was able to mount the DevDevice

bool makeFileSystem(string type, string name)

Trys to create a new file system of the given type with the given name.

The created filesystem will be added to the system DevDevice.

Parameters
Name Type Description

type

string

the type of the new filesystem

  • tmpfs

    A temporary filesystem only existing at runtime in the memory of your computer. All data will be lost when the system stops.

name

string

the name of the new filesystem you want to create

Return Values
Name Type Description

bool

bool

returns true if it was able to create the new filesystem

bool removeFileSystem(string name)

Trys to remove the filesystem with the given name from the system DevDevice.

All mounts of the device will run invalid.

Parameters
Name Type Description

name

string

the name of the new filesystem you want to remove

Return Values
Name Type Description

bool

bool

returns true if it was able to remove the new filesystem

mount(string device, string mountPoint)

This function mounts the device referenced by the the path to a device node to the given mount point.

Parameters
Name Type Description

device

string

the path to the device you want to mount

mountPoint

string

the path to the point were the device should get mounted to

bool unmount(string mountPoint)

This function unmounts if the device at the given mount point.

Parameters
Name Type Description

mountPoint

string

the path the device is mounted to

Return Values
Name Type Description

bool

bool

returns true if it was able to unmount the device located at the mount point

File open(string path, string mode)

Opens a file-stream and returns it as File-table.

Parameters
Name Type Description

path

string

the path to the file you want to open a file-stream for

mode

string

The mode for the file stream

  • r read only

    file stream can just read from file.

    If file doesn’t exist, open will return nil

  • w write

    file stream can read and write

    creates the file if it doesn’t exist

  • a end of file

    file stream can read and write

    cursor is set to the end of file

  • +r truncate

    file stream can read and write

    all previous data in file gets dropped

  • +a append

    file stream can read the full file but can only write to the end of the existing file

Return Values
Name Type Description

File

File

The File table of the file stream

Nil if not able to open file in read only

bool createDir(string path, bool all)

Creates the folder path.

Parameters
Name Type Description

path

string

folder path the function should create

all

bool

If false creates only the last folder of the path
If true creates all folders in the path

Return Values
Name Type Description

bool

bool

returns if it was able to create the directory

bool remove(string path, bool all)

Removes the filesystem object at the given path.

Parameters
Name Type Description

path

string

path to the filesystem object

all

bool

If false only removes the given filesystem object
If true removes all childs of the filesystem object

Return Values
Name Type Description

bool

bool

returns if it was able to remove the node

bool move(string from, string to)

Moves the filesystem object from the given path to the other given path.

Function fails if it is not able to move the object.

Parameters
Name Type Description

from

string

path to the filesystem object you want to move

to

string

path to the filesystem object the target should get moved to

Return Values
Name Type Description

bool

bool

returns true if it was able to move the node

bool rename(string path, string name)

Renames the filesystem object at the given path to the given name.

Parameters
Name Type Description

path

string

path to the filesystem object you want to rename

name

string

the new name for your filesystem object

Return Values
Name Type Description

bool

bool

returns true if it was able to rename the node

array childs(string path)

Lists all children of this node. (f.e. items in a folder)

Parameters
Name Type Description

path

string

path to the filesystem object you want to get the childs from

Return Values
Name Type Description

array

array

array of string which are the names of the childs

array children(string path)

Lists all children of this node. (f.e. items in a folder)

Parameters
Name Type Description

path

string

path to the filesystem object you want to get the childs from

Return Values
Name Type Description

array

array

array of string which are the names of the childs

bool exists(string path)

Checks if the given path exists.

Parameters
Name Type Description

path

string

path you want to check if it exists

Return Values
Name Type Description

bool

bool

true if given path exists

bool isFile(string path)

Checks if path refers to a file.

Parameters
Name Type Description

path

string

path you want to check if it refers to a file

Return Values
Name Type Description

bool

bool

true if path refers to a file

bool isDir(string path)

Checks if given path refers to a directory.

Parameters
Name Type Description

path

string

path you want to check if it refers to a directory

Return Values
Name Type Description

bool

bool

returns true if path refers to a directory

doFile(string path)

Executes Lua code in the file referd by the given path.

Function fails if path doesn’t exist or path doesn’t refer to a file.

Parameters
Name Type Description

path

string

path to file you want to execute as Lua code

function loadFile(string path)

Loads the file refered by the given path as a Lua function and returns it.

Functions fails if path doesn’t exist or path doesn’t reger to a file.

Parameters
Name Type Description

path

string

path to the file you want to load as Lua function

Return Values
Name Type Description

function

function

the file compiled as Lua function

string path([int,] string…​)

Combines a variable amount of strings as paths together to one big path.

Additionally, applies given conversion.

Parameters
Name Type Description

int

int

This optional parameter defines a conversion that should get applied to the output path.
Following Conversions are possible:

0

Normalize the path.
/my/../weird/./path/weird/path

1

Normalizes and converts the path to an absolute path.
my/abs/path/my/abs/path

2

Normalizes and converts the path to an relative path.
/my/relative/pathmy/relative/path

3

Returns the whole file/folder name.
/path/to/file.txtfile.txt

4

Returns the stem of the filename.
/path/to/file.txtfile
/path/to/.file.file

5

Returns the file-extension of the filename.
/path/to/file.txt.txt
/path/to/.file → empty-str
/path/to/file..

Return Values
Name Type Description

string

string

the final combined and converted output path

int…​ analyzePath(string…​)

Each string will be viewed as one filesystem-path and will be checked for lexical features. Each of those string will then have a integer return value which is a bit-flag-register describing those lexical features.

Parameters
Name Type Description

string…​

string…​

filesystem-paths you want to get lexical features from.

Return Values
Name Type Description

int…​

int…​

bit-registers describing the features of each path with following bit assignments:

1

Is filesystem root

2

Is Empty (includes if it is root-path)

3

Is absolute path

4

Is only a file/folder name

5

Filename has extension

6

Ends with a / → refers a directory

bool.. isNode(string…​)

For each given string, returns a bool to tell if string is a valid node (file/folder) name.

Parameters
Name Type Description

string…​

string…​

node-names you want to check.

Return Values
Name Type Description

bool…​

bool…​

True if the corresponding string is a valid node-name.

File

Represents a filestream for reading and writing from and to a file in the virtual filesystem.

Reimplemented from the Lua standard library. Here you can find more.