fs +linux +x86_64

The fs module provides an abstracted interface for accessing an arbitrary filesystem. If you want to work with the host filesystem, you probably want to refer to the functions available in os instead, which provides an implementation of fs::fs for the host filesystem.

Index

Types

type dirent;
type filestat;
type finishfunc;
type flags;
type fs;
type iterator;
type mode;
type nextfunc;
type stat_mask;

// Undocumented types:
type chmodfunc;
type chownfunc;
type closefunc;
type createfilefunc;
type createfunc;
type iterfunc;
type linkfunc;
type mkdirfunc;
type openfilefunc;
type openfunc;
type readlinkfunc;
type removefunc;
type renamefunc;
type resolvefunc;
type rmdirfunc;
type statfunc;
type symlinkfunc;

Errors

type cannotrename;
type error;
type wrongtype;

Functions

fn chmod(*fs, str, mode) (void | error);
fn chown(*fs, str, uint, uint) (void | error);
fn close(*fs) void;
fn create(*fs, str, mode, flags...) (io::handle | error);
fn create_file(*fs, str, mode, flags...) (io::file | error);
fn dirent_dup(*dirent) dirent;
fn dirent_finish(*dirent) void;
fn dirents_free([]dirent) void;
fn exists(*fs, str) bool;
fn finish(*iterator) void;
fn isblockdev(mode) bool;
fn ischdev(mode) bool;
fn isdir(mode) bool;
fn isfifo(mode) bool;
fn isfile(mode) bool;
fn islink(mode) bool;
fn issocket(mode) bool;
fn iter(*fs, str) (*iterator | error);
fn link(*fs, str, str) (void | error);
fn mkdir(*fs, str) (void | error);
fn mkdirs(*fs, str) (void | error);
fn mode_perm(mode) mode;
fn mode_str(mode) const str;
fn mode_type(mode) mode;
fn move(*fs, str, str) (void | error);
fn next(*iterator) (dirent | void);
fn open(*fs, str, flags...) (io::handle | error);
fn open_file(*fs, str, flags...) (io::file | error);
fn readdir(*fs, str) ([]dirent | error);
fn readlink(*fs, str) (str | error);
fn realpath(*fs, str) (str | error);
fn remove(*fs, str) (void | error);
fn rename(*fs, str, str) (void | error);
fn resolve(*fs, str) str;
fn rmdir(*fs, str) (void | error);
fn rmdirall(*fs, str) (void | error);
fn stat(*fs, str) (filestat | error);
fn strerror(error) const str;
fn symlink(*fs, str, str) (void | error);

Types

type dirent[link]

type dirent = struct {
	// The name of this entry. Not fully qualified: for example,
// "foo/bar/baz.txt" would store "baz.txt" here.
name: str, // The type of this entry. The permission bits may be unset.
ftype: mode, };

An entry in a directory. This may be borrowed from the filesystem's internal state. If you want to keep this around beyond one call to next, use dirent_dup.

type filestat[link]

type filestat = struct {
	mask: stat_mask,
	mode: mode,
	uid: uint,
	gid: uint,
	sz: size,
	inode: u64,
	atime: time::instant,
	mtime: time::instant,
	ctime: time::instant,
};

Information about a file or directory. The mask field defines what other fields are set; mode is always set.

type finishfunc[link]

type finishfunc = fn(iter: *iterator) void;

A function which frees state associated with an iterator.

type flags[link]

type flags = enum {
	RDONLY = 0,
	WRONLY = 1,
	RDWR = 2,
	CREATE = 64,
	EXCL = 128,
	NOCTTY = 256,
	TRUNC = 512,
	APPEND = 1024,
	NONBLOCK = 2048,
	DSYNC = 4096,
	SYNC = 1052672,
	RSYNC = 1052672,
	DIRECTORY = 65536,
	NOFOLLOW = 131072,
	NOATIME = 262144,
	CLOEXEC = 524288,
	PATH = 2097152,
	TMPFILE = 4259840,

};

Flags to use for opening a file. Not all operating systems support all flags; at a minimum, RDONLY, WRONLY, RDWR, and CREATE will be supported.

type fs[link]

type fs = struct {
	// Frees resources associated with this filesystem.
close: nullable *closefunc, // Opens a file.
open: nullable *openfunc, // Opens a file as an [[io::file]].
openfile: nullable *openfilefunc, // Creates a new file.
create: nullable *createfunc, // Creates a new file as an [[io::file]].
createfile: nullable *createfilefunc, // Removes a file.
remove: nullable *removefunc, // Renames a file.
rename: nullable *renamefunc, // Returns an iterator for a path, which yields the contents of a
// directory. Pass empty string to yield from the root.
//
// The iterator must return all entries without error. If an error would
// occur, it should be identified here and returned upfront.
iter: nullable *iterfunc, // Obtains information about a file or directory. If the target is a
// symbolic link, information is returned about the link, not its
// target.
stat: nullable *statfunc, // Returns the path referred to by a symbolic link. The caller will free
// the return value.
readlink: nullable *readlinkfunc, // Creates a directory.
mkdir: nullable *mkdirfunc, // Removes a directory. The target directory must be empty.
rmdir: nullable *rmdirfunc, // Changes mode flags on a file or directory.
chmod: nullable *chmodfunc, // Changes ownership of a file.
chown: nullable *chownfunc, // Resolves a path to its absolute, normalized value. If the fs
// implementation does not provide this, [resolve] presumes that
// relative paths are rooted (i.e. "foo" == "/foo").
resolve: nullable *resolvefunc, // Creates a new (hard) link.
link: nullable *linkfunc, // Creates a new symbolic link.
symlink: nullable *symlinkfunc, };

An abstract implementation of a filesystem, which provides common filesystem operations such as file creation and deletion, but which may be backed by any underlying storage system. See os::cwd for access to the host filesystem.

To create a custom filesystem implementation, embed this type as the first member of a struct with user-specific data and fill out these fields as appropriate.

type iterator[link]

type iterator = struct {
	// Returns the next member of the directory, or void if there are none
// remaining.
next: *nextfunc, // Frees resources associated with the iterator.
finish: nullable *finishfunc, };

A directory iterator. To implement a directory iterator for a filesystem, subtype this struct to store any necessary state and populate the pointers with your implementation.

type mode[link]

type mode = enum uint {
	USER_RWX = 448, // Read, write, and execute permissions for the file owner
USER_RW = 384, // Read and write permissions for the file owner
USER_RX = 320, // Read and execute permissions for the file owner
USER_R = 256, // Read permissions for the file owner
USER_W = 128, // Write permissions for the file owner
USER_X = 64, // Execute permissions for the file owner
GROUP_RWX = 56, // Read, write, and execute permissions for group members
GROUP_RW = 48, // Read and write permissions for group members
GROUP_RX = 40, // Read and execute permissions for group members
GROUP_R = 32, // Read permissions for group members
GROUP_W = 16, // Write permissions for group members
GROUP_X = 8, // Execute permissions for group members
OTHER_RWX = 7, // Read, write, and execute permissions for other users
OTHER_RW = 6, // Read and write permissions for other users
OTHER_RX = 5, // Read and execute permissions for other users
OTHER_R = 4, // Read permissions for other users
OTHER_W = 2, // Write permissions for other users
OTHER_X = 1, // Execute permissions for other users
SETUID = 2048, // Entry has the set-uid bit set
SETGID = 1024, // Entry has the set-gid bit set
STICKY = 512, // Entry has the sticky bit set
UNKNOWN = 0, // Entry is of an unknown type
FIFO = 4096, // Entry is a FIFO (named pipe)
DIR = 16384, // Entry is a directory
CHR = 8192, // Entry is a character device
BLK = 24576, // Entry is a block device
REG = 32768, // Entry is a regular file
LINK = 40960, // Entry is a symbolic link
SOCK = 49152, // Entry is a Unix socket
};

File mode information. These bits do not necessarily reflect the underlying operating system's mode representation, though they were chosen to be consistent with typical Unix file permissions. All implementations shall support at least USER_RW, DIR, and REG.

type nextfunc[link]

type nextfunc = fn(iter: *iterator) (dirent | void);

A function which returns the next directory from an iterator.

type stat_mask[link]

type stat_mask = enum uint {
	UID = 1 << 0,
	GID = 1 << 1,
	SIZE = 1 << 2,
	INODE = 1 << 3,
	ATIME = 1 << 4,
	MTIME = 1 << 5,
	CTIME = 1 << 6,

};

A mask defining what items are populated in the stat structure.

type chmodfunc[link]

Show undocumented member
type chmodfunc = fn(fs: *fs, path: str, mode: mode) (void | error);

type chownfunc[link]

Show undocumented member
type chownfunc = fn(fs: *fs, path: str, uid: uint, gid: uint) (void | error);

type closefunc[link]

Show undocumented member
type closefunc = fn(fs: *fs) void;

type createfilefunc[link]

Show undocumented member
type createfilefunc = fn(fs: *fs, path: str, mode: mode, flags: flags...) (io::file | error);

type createfunc[link]

Show undocumented member
type createfunc = fn(fs: *fs, path: str, mode: mode, flags: flags...) (io::handle | error);

type iterfunc[link]

Show undocumented member
type iterfunc = fn(fs: *fs, path: str) (*iterator | error);

type linkfunc[link]

Show undocumented member
type linkfunc = fn(fs: *fs, old: str, new: str) (void | error);

type mkdirfunc[link]

Show undocumented member
type mkdirfunc = fn(fs: *fs, path: str) (void | error);

type openfilefunc[link]

Show undocumented member
type openfilefunc = fn(fs: *fs, path: str, flags: flags...) (io::file | error);

type openfunc[link]

Show undocumented member
type openfunc = fn(fs: *fs, path: str, flags: flags...) (io::handle | error);

type readlinkfunc[link]

Show undocumented member
type readlinkfunc = fn(fs: *fs, path: str) (str | error);

type removefunc[link]

Show undocumented member
type removefunc = fn(fs: *fs, path: str) (void | error);

type renamefunc[link]

Show undocumented member
type renamefunc = fn(fs: *fs, oldpath: str, newpath: str) (void | error);

type resolvefunc[link]

Show undocumented member
type resolvefunc = fn(fs: *fs, path: str) str;

type rmdirfunc[link]

Show undocumented member
type rmdirfunc = fn(fs: *fs, path: str) (void | error);

type statfunc[link]

Show undocumented member
type statfunc = fn(fs: *fs, path: str) (filestat | error);

type symlinkfunc[link]

Show undocumented member
type symlinkfunc = fn(fs: *fs, target: str, path: str) (void | error);

Errors

type cannotrename[link]

type cannotrename = !void;

Returned from rename if this rename is not possible due to technical constraints, such as if it would cause a file to move between filesystems. In this situation, other operations (such as copy & remove) may succeed if attempted.

type error[link]

type error = !(errors::noentry | errors::noaccess | errors::exists | errors::busy |
errors::invalid | errors::unsupported | wrongtype | cannotrename |
io::error);

All possible fs error types.

type wrongtype[link]

type wrongtype = !void;

An entry of a particular type was sought, but is something else in practice. For example, opening a file with iter.

Functions

fn chmod[link]

fn chmod(fs: *fs, path: str, mode: mode) (void | error);

Changes mode flags on a file or directory.

fn chown[link]

fn chown(fs: *fs, path: str, uid: uint, gid: uint) (void | error);

Changes ownership of a file.

fn close[link]

fn close(fs: *fs) void;

Closes a filesystem. The fs cannot be used after this function is called.

fn create[link]

fn create(fs: *fs, path: str, mode: mode, flags: flags...) (io::handle | error);

Creates a new file and opens it for writing. If no flags are provided, the default read/write mode is WRONLY.

fn create_file[link]

fn create_file(fs: *fs, path: str, mode: mode, flags: flags...) (io::file | error);

Creates a new file, as an io::file, and opens it for writing. This file will be backed by an open file handle on the host operating system, which may not be possible with all filesystem implementations (such cases will return io::unsupported).

If no flags are provided, the default read/write mode is WRONLY.

fn dirent_dup[link]

fn dirent_dup(e: *dirent) dirent;

Duplicates a dirent object. Call dirent_finish to get rid of it later.

fn dirent_finish[link]

fn dirent_finish(e: *dirent) void;

Frees memory associated with a dirent object which was duplicated with dirent_dup.

fn dirents_free[link]

fn dirents_free(d: []dirent) void;

Frees a slice of dirents.

fn exists[link]

fn exists(fs: *fs, path: str) bool;

Returns true if a node exists at the given path, or false if not.

Note that testing for file existence before using the file can often lead to race conditions. If possible, prefer to simply attempt to use the file (e.g. via "open"), and handle the resulting error should the file not exist.

fn finish[link]

fn finish(iter: *iterator) void;

Frees state associated with an iterator.

fn isblockdev[link]

fn isblockdev(mode: mode) bool;

Returns true if this item is a block device.

fn ischdev[link]

fn ischdev(mode: mode) bool;

Returns true if this item is a character device.

fn isdir[link]

fn isdir(mode: mode) bool;

Returns true if this item is a directory.

fn isfifo[link]

fn isfifo(mode: mode) bool;

Returns true if this item is a FIFO (named pipe).

fn isfile[link]

fn isfile(mode: mode) bool;

Returns true if this item is a regular file.

fn islink(mode: mode) bool;

Returns true if this item is a symbolic link.

fn issocket[link]

fn issocket(mode: mode) bool;

Returns true if this item is a Unix socket.

fn iter[link]

fn iter(fs: *fs, path: str) (*iterator | error);

Returns an iterator for a path, which yields the contents of a directory. Pass empty string to yield from the root. The order in which entries are returned is undefined.

fn link(fs: *fs, old: str, new: str) (void | error);

Creates a new (hard) link at 'new' for the file at 'old'.

fn mkdir[link]

fn mkdir(fs: *fs, path: str) (void | error);

Creates a directory.

fn mkdirs[link]

fn mkdirs(fs: *fs, path: str) (void | error);

Makes a directory, and all non-extant directories in its path.

fn mode_perm[link]

fn mode_perm(m: mode) mode;

Returns the permission bits of a file mode.

fn mode_str[link]

fn mode_str(m: mode) const str;

Converts a mode into a Unix-like mode string (e.g. "-rw-r--r--"). The string is statically allocated, use strings::dup to duplicate it or it will be overwritten on subsequent calls.

fn mode_type[link]

fn mode_type(m: mode) mode;

Returns the type bits of a file mode.

fn move[link]

fn move(fs: *fs, oldpath: str, newpath: str) (void | error);

Moves a file. This will use rename if possible, and will fall back to copy and remove if necessary.

fn next[link]

fn next(iter: *iterator) (dirent | void);

Returns the next directory entry from an iterator, or void if none remain. It is a programming error to call this again after it has returned void. The file stat returned may only have the type bits set on the file mode; callers should call stat to obtain the detailed file mode.

fn open[link]

fn open(fs: *fs, path: str, flags: flags...) (io::handle | error);

Opens a file. If no flags are provided, the default read/write mode is RDONLY.

fn open_file[link]

fn open_file(fs: *fs, path: str, flags: flags...) (io::file | error);

Opens a file, as an io::file. This file will be backed by an open file handle on the host operating system, which may not be possible with all filesystem implementations (such cases will return io::unsupported).

If no flags are provided, the default read/write mode is RDONLY.

fn readdir[link]

fn readdir(fs: *fs, path: str) ([]dirent | error);

Reads all entries from a directory. The caller must free the return value with dirents_free.

fn readlink(fs: *fs, path: str) (str | error);

Returns the path referred to by a symbolic link. The return value is statically allocated and will be overwritten on subsequent calls.

fn realpath[link]

fn realpath(fs: *fs, path: str) (str | error);

Canonicalizes a path in this filesystem by resolving all symlinks and collapsing any "." or ".." path components. The return value is statically allocated and will be overwritten on subsequent calls.

fn remove[link]

fn remove(fs: *fs, path: str) (void | error);

Removes a file.

fn rename[link]

fn rename(fs: *fs, oldpath: str, newpath: str) (void | error);

Renames a file. This generally only works if the source and destination path are both on the same filesystem. See move for an implementation which falls back on a "copy & remove" procedure in this situation.

fn resolve[link]

fn resolve(fs: *fs, path: str) str;

Resolves a path to its absolute, normalized value. Relative paths will be rooted (if supported by the fs implementation), and "." and ".." components will be reduced. This function does not follow symlinks; see realpath if you need this behavior. The return value is statically allocated; use strings::dup to extend its lifetime.

fn rmdir[link]

fn rmdir(fs: *fs, path: str) (void | error);

Removes a directory. The target directory must be empty; see rmdirall to remove its contents as well.

fn rmdirall[link]

fn rmdirall(fs: *fs, path: str) (void | error);

Removes a directory, and anything in it.

fn stat[link]

fn stat(fs: *fs, path: str) (filestat | error);

Obtains information about a file or directory. If the target is a symlink, information is returned about the link, not its target.

fn strerror[link]

fn strerror(err: error) const str;

Returns a human-friendly representation of an error.

fn symlink(fs: *fs, target: str, path: str) (void | error);

Creates a new symbolic link at 'path' which points to 'target'.