fs

File operations relative to the script's data directory. The directory is created by the first write or mkdir call.

All failures return nil or false followed by a reason string; fs functions do not raise. Reasons include "path", "no data directory", "data must be a string", "not found", "read failed", "file too large", "write failed" and operating-system messages.

fs.data_dirCopy Anchor Link

fs.data_dir()

Returns: absolute data-directory path, or nil, reason.

fs.game_dirCopy Anchor Link

fs.game_dir()

Returns: the process working directory as an absolute UTF-8 path, or nil, reason. Unlike the other fs functions it is outside the data directory, and nothing in fs reads or writes under it.

fs.readCopy Anchor Link

fs.read(path)

Reads the entire file as binary data.

Returns: string, or nil, reason. Missing files and directories return nil, "not found".

fs.writeCopy Anchor Link

fs.write(path, data)

Creates or truncates a file. Missing parent directories are created. data must be a string.

Returns: true, or false, reason.

fs.appendCopy Anchor Link

fs.append(path, data)

Appends string data, creating the file if necessary.

Returns: true, or false, reason.

fs.existsCopy Anchor Link

fs.exists(path)

Returns: boolean, with a reason on failure. A rejected path also returns false; inspect the second value to distinguish failure from absence.

fs.removeCopy Anchor Link

fs.remove(path)

Removes a file or an empty directory. fs.remove('') removes the data directory itself if empty.

Returns: true, or false, reason.

fs.mkdirCopy Anchor Link

fs.mkdir(path)

Creates all directory levels. An existing directory is treated as success.

Returns: true, or false, reason.

fs.listCopy Anchor Link

fs.list(path?)

Lists one directory level. Omit path to list the script's data directory.

Returns: a sorted table of file and directory names, or nil, reason.

Path restrictionsCopy Anchor Link

Paths must be valid UTF-8 strings relative to the data directory. The following are rejected with "path":

• absolute paths, drive prefixes and UNC paths, including C:\x, \\server, /x and \x;
• any .. component;
• any component containing :, including alternate data streams;
• Windows device names, case-insensitive and with any extension: CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9.

Both / and \ are accepted as separators. "" and "." refer to the data directory itself. Validation is textual: links inside the directory are followed. This API is not a security boundary; io and os remain available.