Standard library
Filesystem
Files, directories, metadata, streaming, and chmod.
Introduction
Files, directories, metadata, streaming, and chmod. Import std/fs to bind the module as fs. Call free functions as fs.name(...). Struct methods use a receiver value.
/ std/fs
This page is the package reference for std/fs. Private helpers used only by co-located tests are not listed.
Struct · meta
Metadata product shape for fs.metadata results. The shape is exported as fs.meta. Construct or obtain values through the free functions below when the package provides them.
/ std/fs
; shape: fs.meta
$ m = fs.metadata(p'/tmp')
Parameters: No parameters. Type or shape export. Returns: Shape export used for literals and methods.
Struct · file
Open file handle shape with read, write, seek, and close methods. The shape is exported as fs.file. Methods on the receiver are listed next.
/ std/fs
; shape: fs.file
$ f = fs.open(p'/tmp/echo-demo.txt')
Parameters: No parameters. Type or shape export. Returns: Shape export used for literals and methods.
file · read
Reads up to limit bytes from the open file. Empty bytes mean end of file. I/O failure uses a result err. Call form: file.read(limit).
/ std/fs
$ f = fs.open(p'/tmp/echo-demo.txt')
| f.read(4096) {
$ b { }
! e { }
}Parameters: limit: maximum bytes to read. Returns: Result. Ok arm: bytes. Err arm: "read failed".
file · write
Writes data to the open file. Data may be bytes or a string. Call form: file.write(data).
/ std/fs
$ f = fs.open(p'/tmp/echo-demo.txt')
| f.write("more\n") {
$ _ { }
! e { }
}Parameters: data: bytes or string to write. Returns: Result. Ok arm: none. Err arm: "write failed".
file · seek
Moves the file position to an absolute byte offset. Call form: file.seek(pos).
/ std/fs
$ f = fs.open(p'/tmp/echo-demo.txt')
| f.seek(0) {
$ pos { }
! e { }
}Parameters: pos: absolute byte position. Returns: Result. Ok arm: new position. Err arm: "seek failed".
file · close
Closes the file handle and marks the product closed. Call form: file.close().
/ std/fs
$ f = fs.open(p'/tmp/echo-demo.txt')
f.close()
Parameters: No parameters. Returns: The file receiver (for chaining).
Functions
Free functions on fs. Each function has a short description, an example, then parameters and return shape.
exists
Reports whether path exists in the file system. Call form: fs.exists(path).
/ std/fs
$ ok = fs.exists(p'/tmp')
Parameters: path: file path as string or locator. Returns: Boolean true when the path exists.
is_file
Reports whether path names a regular file. Call form: fs.is_file(path).
/ std/fs
$ ok = fs.is_file(p'/tmp/a.txt')
Parameters: path: file path as string or locator. Returns: Boolean true when path is a file.
is_dir
Reports whether path names a directory. Call form: fs.is_dir(path).
/ std/fs
$ ok = fs.is_dir(p'/tmp')
Parameters: path: file path as string or locator. Returns: Boolean true when path is a directory.
join
Joins path segments with platform rules (same bridge as path.join). Call form: fs.join(base, rel).
/ std/fs
$ p = fs.join("/tmp", "a.txt")Parameters: base: base path. rel: relative segment. Returns: Joined path string.
read
Reads the entire file at path as bytes. Path accepts a string or locator. Call form: fs.read(path).
/ std/fs
$ data = fs.read(p'/tmp/echo-demo.txt')
Parameters: path: file path as string or locator. Returns: Bytes of the file contents.
write
Writes data to path, creating or replacing the file. Data may be bytes or a string (UTF-8). Call form: fs.write(path, data).
/ std/fs
fs.write(p'/tmp/echo-demo.txt', "hello\n")
Parameters: path: file path as string or locator. data: bytes or string to write. Returns: None on success.
remove
Removes a file at path. Call form: fs.remove(path).
/ std/fs
fs.remove(p'/tmp/echo-demo.txt')
Parameters: path: file path as string or locator. Returns: None.
copy
Copies a file from path to to. Call form: fs.copy(from, to).
/ std/fs
fs.copy(p'/tmp/a', p'/tmp/b')
Parameters: path: source path. to: destination path. Returns: None on success.
rename
Renames or moves a file from path to to. Call form: fs.rename(from, to).
/ std/fs
fs.rename(p'/tmp/a', p'/tmp/b')
Parameters: path: source path. to: destination path. Returns: None on success.
create_dir
Creates a single directory at path. Call form: fs.create_dir(path).
/ std/fs
fs.create_dir(p'/tmp/echo-dir')
Parameters: path: directory path as string or locator. Returns: None on success.
create_dir_all
Creates path and any missing parent directories. Call form: fs.create_dir_all(path).
/ std/fs
fs.create_dir_all(p'/tmp/echo/nested')
Parameters: path: directory path as string or locator. Returns: None on success.
read_dir
Lists immediate child names of a directory. Call form: fs.read_dir(path).
/ std/fs
| fs.read_dir(p'.') {
$ names { }
! e { }
}Parameters: path: directory path as string or locator. Returns: Result. Ok arm: list of entry name strings. Err arm: failure message.
remove_dir
Removes an empty directory at path. Call form: fs.remove_dir(path).
/ std/fs
fs.remove_dir(p'/tmp/echo-dir')
Parameters: path: directory path as string or locator. Returns: None.
metadata
Reads metadata for path into a meta product. Call form: fs.metadata(path).
/ std/fs
$ m = fs.metadata(p'/tmp')
Parameters: path: file path as string or locator. Returns: meta product with len, is_file, is_dir, is_symlink, modified_ms.
open
Opens an existing file for streaming read and write. Call form: fs.open(path).
/ std/fs
$ f = fs.open(p'/tmp/echo-demo.txt')
Parameters: path: file path as string or locator. Returns: file product with handle and methods read, write, seek, close.
create
Creates or truncates a file for streaming I/O. Call form: fs.create(path).
/ std/fs
$ f = fs.create(p'/tmp/echo-new.txt')
Parameters: path: file path as string or locator. Returns: file product with handle and methods.
append
Opens a file for append writes. Call form: fs.append(path).
/ std/fs
$ f = fs.append(p'/tmp/echo-demo.txt')
Parameters: path: file path as string or locator. Returns: file product opened for append.
temp_dir
Returns the process temporary directory path. Call form: fs.temp_dir().
/ std/fs
$ t = fs.temp_dir()
Parameters: No parameters. Returns: Temp directory path string.
create_temp
Creates a temporary file and returns its path. Call form: fs.create_temp(prefix).
/ std/fs
$ p = fs.create_temp()
Parameters: No parameters. Returns: Path string of the new temp file.
symlink
Creates a symbolic link at path pointing to target. Call form: fs.symlink(original, link).
/ std/fs
fs.symlink(p'/tmp/link', p'/tmp/a')
Parameters: path: link path. target: link target path. Returns: None on success.
chmod
Sets permission bits on path. Call form: fs.chmod(path, mode).
/ std/fs
fs.chmod(p'/tmp/a', 0o644)
Parameters: path: file path as string or locator. mode: mode bits. Returns: None.