symlink(src, dst) -> ok, err

Create a symbolic link

Creates a symbolic link at dst pointing to src. The argument order matches ln -s src dst. Returns nil and an error string on failure.

chmod(path, mode) -> ok, err

Change file mode bits

Changes the permission bits of the file at path. Mode is an octal string (e.g. "0755"). Returns nil and an error string on failure.

cwd() -> path

Get the current working directory

Returns the absolute path of the process's current working directory. Wraps getcwd(2). Returns an empty string if the path cannot be determined.

chdir(path) -> ok, err

Change the current working directory

Changes the process's current working directory to path. Returns true on success, or nil and an error string on failure (e.g., path does not exist or permission denied).

stat(path) -> info, err

Get file or directory status information

Returns a table with fields: mode (file type character), size, perms, uid, gid, atime, mtime, ctime, dev, ino. Returns nil and error on failure.

readlink(pathname) -> target, err

Read the target of a symbolic link

Returns the raw link target exactly as stored (does not resolve further symlinks or relative paths). Wraps readlink(2). Returns nil and an error string if path is not a symlink or cannot be read.

split_path_by_dir(pathname) -> dirs

Split a pathname into an array of directory components

Splits a pathname on / separators and returns the components as an ordered array. Leading slashes are discarded; the final component is included even if it names a file rather than a directory.

Example: split_path_by_dir("/usr/local/bin") → {"usr","local","bin"}

mkdir(pathname, mode, recursive) -> ok, err

Create a directory, optionally with parent directories

mode is an octal permission string passed to mkdir(2), e.g. "0755". Defaults to "0755" (subject to umask) when omitted. When recursive is true, any missing parent directories are created in order, each with the same mode. Returns nil and an error string if creation fails at any step.

list_dir(path) -> entries, err

List all entries in a directory

Returns an array of filenames for every entry in path, including "." and "..". The array is unordered. Returns nil and an error string if the path does not exist or is not a directory.

fast_list_dir(path) -> entries, err

List directory entries using optimized syscall

Same return shape as list_dir (array of filenames including "." and ".."), but uses the getdents64 syscall directly, avoiding per-entry stat calls. Faster than list_dir for large directories. Returns nil and an error string on failure.

empty_dir(path) -> is_empty, err

Check if a directory is empty

Returns true if the directory exists and contains no entries (only "." and ".." entries). Returns nil and an error message if the path doesn't exist or isn't a directory.

non_empty_dir(path) -> is_non_empty, err

Check if a directory is non-empty

Returns true if the directory exists and contains entries beyond "." and "..". Returns nil and an error message if the path doesn't exist or isn't a directory.

remove(path, recursive) -> ok, err

Remove a file or directory

Removes a file or directory. If recursive is true and the path is a directory, all contents are removed recursively. Returns nil and an error if the path doesn't exist or cannot be removed.

rename(src, dst) -> ok, err

Rename or move a file or directory

Renames or moves a file or directory from src to dst. If dst is an existing directory, src is moved inside it. Returns an error on failure.

list_files(dir, pattern, mode, resolve_links) -> files, err

List files in a directory matching a pattern and mode

Returns a table keyed by filename, with each value containing mode, size, perms, uid, gid, atime, and optionally target fields. Default pattern is ^.*, default mode is "f".

dir_exists(filename) -> exists

Check if a directory exists at the given path

Returns true if the path exists and is a directory, false otherwise.

file_exists(filename, mode) -> exists

Check if a file exists and matches the given mode

Returns true if the path exists and matches the given mode (e.g., "f" for regular file, "d" for directory, "l" for symlink). Defaults to "f".

read_file(filename) -> content, err

Read the entire contents of a file

Reads the file at the given path and returns its contents as a string. Returns nil and an error message if the file cannot be read.

write_file(filename, text) -> ok, err

Write text content to a file

Opens path for writing (mode "w+"), which creates the file if it does not exist and truncates it if it does. Writes text and closes the file. Returns true on success, or nil and an error string on failure.

fdopen(fd, mode) -> file, err

Convert a raw file descriptor to a Lua FILE* object

Transforms a raw file descriptor into a Lua FILE* object. Mode: "r" for read, "w" for write, "a" for append. The original fd is closed; the FILE* owns a duplicate descriptor.