Module `system.filesystem`¶

The filesystem module implements common operations for working with the filesystem, including wrappers for syscalls.

Index¶

Function

`absolute()`	Gets the absolute path from a path string.
`basename()`	Returns the file name for a path.
`chmod()`	Changes the permissions (mode) of the file at a path.
`chown()`	Changes the owner of a file or directory.
`chroot()`	Changes the root directory of the current and future child processes. This function requires root.
`combine()`	Combines the specified path components into a single path, canonicalizing any links and ./.. paths.
`copy()`	Copies a file or directory.
`dirname()`	Returns the parent directory for a path.
`effectivePermissions()`	Returns the effective permissions on a file or stat entry for the selected user.
`exists()`	Convenience function for determining whether a file exists. This simply checks that stat does not return nil.
`find()`	Searches the filesystem for paths matching a glob-style wildcard.
`fsevent()`	Registers the process to receive filesystem events for a path. Note that this is not recursive.
`isDir()`	Returns whether the path exists and is a directory.
`isFile()`	Returns whether the path exists and is a file.
`isLink()`	Returns whether the path exists and is a link.
`link()`	Creates a (symbolic) link to a file.
`list()`	Returns a list of files in a directory.
`mkdir()`	Creates a directory, making any parent paths that don't exist.
`mkfifo()`	Creates a FIFO.
`mount()`	Mounts a filesystem of the specified type to a directory.
`mountlist()`	Returns a list of mounts currently available.
`move()`	Moves a file or directory, allowing cross-filesystem operations.
`open()`	Opens a file for reading or writing.
`remove()`	Deletes a file or directory at a path, removing any subentries if present.
`rename()`	Moves a file or directory on the same filesystem.
`stat()`	Returns a table with various information about a file or directory.
`unmount()`	Unmounts a mounted filesystem.

Class

FileStat

A table which stores file statistics.

API Reference¶

system.filesystem.open(path: string, mode: string): ( handle: system.filesystem.FileHandle | nil, err: string | nil )¶

Opens a file for reading or writing.

Parameters:

path (string) – The path to the file to open
mode (string) – The mode to open the file in: [rwa]b?

Returns:

handle (system.filesystem.FileHandle | nil) – The file handle, which has the same functions as CraftOS file handles
err (string | nil) – An error message describing why the file couldn’t be opened

system.filesystem.list(path: string): (result: table)¶

Returns a list of files in a directory.

Parameters:: path (string) – The path to query
Returns:: result (table) – A list of files and folders in the directory

system.filesystem.stat(path: string, nolink?: boolean): (result: system.filesystem.FileStat)¶

Returns a table with various information about a file or directory.

Parameters:

path (string) – The path to query
nolink? (boolean) – Whether to not resolve links to the file (defaults to false)

Returns:

result (system.filesystem.FileStat) – A table with information about the path

system.filesystem.remove(path: string): unknown¶

Deletes a file or directory at a path, removing any subentries if present.

Parameters:: path (string) – The path to remove

system.filesystem.rename(from: string, to: string): unknown¶

Moves a file or directory on the same filesystem.

Parameters:

from (string) – The original file to move
to (string) – The new path for the file

system.filesystem.mkdir(path: string): unknown¶

Creates a directory, making any parent paths that don’t exist.

Parameters:: path (string) – The directory to create

system.filesystem.link(path: string, location: string): unknown¶

Creates a (symbolic) link to a file.

Parameters:

path (string) – The path of the new link
location (string) – The location to point the link to

system.filesystem.mkfifo(path: string): unknown¶

Creates a FIFO.

Parameters:: path (string) – The FIFO to create

system.filesystem.chmod( path: string, user: string | nil, mode: string | number | {read: boolean, write: boolean, execute: boolean} ): unknown¶

Changes the permissions (mode) of the file at a path.

Parameters:

path (string) – The path to modify
user (string | nil) – The user to modify, or nil to modify world permissions
mode (string | number | {read: boolean, write: boolean, execute: boolean}) – The new permissions, as either an octal bitmask, a string in the format “[+-=][rwx]+” or “[r-][w-][x-]”, or a table with the permissions to set (any nil arguments are left unset).

system.filesystem.chown(path: string, user: string): unknown¶

Changes the owner of a file or directory.

Parameters:

path (string) – The path to modify
user (string) – The new owner of the file

system.filesystem.chroot(path: string): unknown¶

Changes the root directory of the current and future child processes. This function requires root.

Parameters:: path (string) – The new root path to change to

system.filesystem.mount(type: string, src: string, dest: string, options?: table): unknown¶

Mounts a filesystem of the specified type to a directory.

Parameters:

type (string) – The type of filesystem to mount
src (string) – The source of the mount (depends on the FS type)
dest (string) – The destination directory to mount to
options? (table) – A table of options to pass to the filesystem

system.filesystem.unmount(path: string): unknown¶

Unmounts a mounted filesystem.

Parameters:: path (string) – The filesystem to unmount

system.filesystem.mountlist(): ( result: {path: string, type: string, source: string, options: table}[] )¶

Returns a list of mounts currently available.

Returns:: result ({path: string, type: string, source: string, options: table}[]) – A list of mounts and their properties.

system.filesystem.fsevent(path: string, enabled?: boolean): unknown¶

Registers the process to receive filesystem events for a path. Note that this is not recursive.

Parameters:

path (string) – The path to register for
enabled? (boolean) – Whether to enable events (defaults to true)

system.filesystem.combine(...: string): (result: string)¶

Combines the specified path components into a single path, canonicalizing any links and ./.. paths.

Parameters:: ... (string) – The path components to combine
Returns:: result (string) – The combined and canonicalized path

system.filesystem.absolute(path: string): (result: string)¶

Gets the absolute path from a path string.

Parameters:: path (string) – The path to convert
Returns:: result (string) – An absolute path pointing to the file

system.filesystem.copy(from: string, to: string, preserve?: boolean)¶

Copies a file or directory.

Parameters:

from (string) – The path to copy from
to (string) – The path to copy to
preserve? (boolean) – Whether to preserve permissions when copying

system.filesystem.move(from: string, to: string)¶

Moves a file or directory, allowing cross-filesystem operations.

Parameters:

from (string) – The path to move from
to (string) – The path to move to

system.filesystem.basename(path: string): (result: string)¶

Returns the file name for a path.

Parameters:: path (string) – The path to use
Returns:: result (string) – The file name of the path

system.filesystem.dirname(path: string): (result: string)¶

Returns the parent directory for a path.

Parameters:: path (string) – The path to use
Returns:: result (string) – The parent directory of the path

system.filesystem.find(wildcard: string): (result: table)¶

Searches the filesystem for paths matching a glob-style wildcard.

Parameters:: wildcard (string) – The pathspec to match
Returns:: result (table) – A list of matching file paths

system.filesystem.exists(path: string): (result: boolean)¶

Convenience function for determining whether a file exists. This simply checks that stat does not return nil.

Parameters:: path (string) – The path to check
Returns:: result (boolean) – Whether the path exists

system.filesystem.isFile(path: string): (result: boolean)¶

Returns whether the path exists and is a file.

Parameters:: path (string) – The path to check
Returns:: result (boolean) – Whether the path is a file

system.filesystem.isDir(path: string): (result: boolean)¶

Returns whether the path exists and is a directory.

Parameters:: path (string) – The path to check
Returns:: result (boolean) – Whether the path is a directory

system.filesystem.isLink(path: string): (result: boolean)¶

Returns whether the path exists and is a link.

Parameters:: path (string) – The path to check
Returns:: result (boolean) – Whether the path is a link

system.filesystem.effectivePermissions( file: string | system.filesystem.FileStat, user?: string ): ( result: {read: boolean, write: boolean, execute: boolean} | nil )¶

Returns the effective permissions on a file or stat entry for the selected user.

Parameters:

file (string | system.filesystem.FileStat) – The file path or stat to check
user? (string) – The user to check for (defaults to the current user)

Returns:

result ({read: boolean, write: boolean, execute: boolean} | nil) – The permissions for the user, or nil if the file doesn’t exist

class system.filesystem.FileStat¶

A table which stores file statistics.

type: string¶: Stores the type of file: one of “file”, “directory”, “link”, “special”

size: integer¶: The size of the file

created: integer¶: The creation date of the file, in milliseconds since January 1, 1970

modified: integer¶: The modification date of the file, in milliseconds since January 1, 1970

owner: string¶: The owner of the file

permissions: table¶: The permissions of the file for each user, indexed by user name

worldPermissions: table¶: The permissions of the file for all users not in FileStat.permissions

special: table¶: Any additional data from the filesystem

Module system.filesystem¶

Index¶

API Reference¶

Module `system.filesystem`¶