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 flag[link]

type flag = enum {
	RDONLY = 0,
	WRONLY = 1,
	RDWR = 2,
	CREATE = 64,
	EXCL = 128,
	CTTY = 256,
	TRUNC = 512,
	APPEND = 1024,
	NONBLOCK = 2048,
	DSYNC = 4096,
	SYNC = 1052672,
	RSYNC = 1052672,
	DIRECTORY = 65536,
	NOFOLLOW = 131072,
	NOATIME = 262144,
	NOCLOEXEC = 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, CREATE, and TRUNC will be supported. Note that NOCTTY and CLOEXEC are on by default, and the CTTY/NOCLOEXEC flags respectively disable them.

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,
	// Obtains information about an [[io::file]].
	fstat: nullable *fstatfunc,
	// 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 mode flags on a [[io::file]].
	fchmod: nullable *fchmodfunc,
	// Changes ownership of a file.
	chown: nullable *chownfunc,
	// Changes ownership of a [[io::file]].
	fchown: nullable *fchownfunc,
	// Changes access and modification time of a file.
	chtimes: nullable *chtimesfunc,
	// Changes access and modification time of an [[io::file]].
	fchtimes: nullable *fchtimesfunc,
	// 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 done 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 | done | error);

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]

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

type chownfunc[link]

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

type chtimesfunc[link]

type chtimesfunc = fn(fs: *fs, path: str, atime: (time::instant | void), mtime: (time::instant | void)) (void | error);

type closefunc[link]

type closefunc = fn(fs: *fs) void;

type createfilefunc[link]

type createfilefunc = fn(fs: *fs, path: str, mode: mode, flags: flag) (io::file | error);

type createfunc[link]

type createfunc = fn(fs: *fs, path: str, mode: mode, flags: flag) (io::handle | error);

type fchmodfunc[link]

type fchmodfunc = fn(fd: io::file, mode: mode) (void | error);

type fchownfunc[link]

type fchownfunc = fn(fd: io::file, uid: uint, gid: uint) (void | error);

type fchtimesfunc[link]

type fchtimesfunc = fn(fd: io::file, atime: (time::instant | void), mtime: (time::instant | void)) (void | error);

type fstatfunc[link]

type fstatfunc = fn(fs: *fs, file: io::file) (filestat | error);

type iterfunc[link]

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

type linkfunc[link]

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

type mkdirfunc[link]

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

type openfilefunc[link]

type openfilefunc = fn(fs: *fs, path: str, flags: flag) (io::file | error);

type openfunc[link]

type openfunc = fn(fs: *fs, path: str, flags: flag) (io::handle | error);

type readlinkfunc[link]

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

type removefunc[link]

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

type renamefunc[link]

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

type resolvefunc[link]

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

type rmdirfunc[link]

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

type statfunc[link]

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

type symlinkfunc[link]

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

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 | utf8::invalid | 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.

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 chtimes[link]

fn chtimes(fs: *fs, path: str, atime: (time::instant | void), mtime: (time::instant | void)) (void | error);

Changes the access and modification time of a file. A void value will leave the corresponding time unchanged.

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: flag = flag::WRONLY | flag::TRUNC) (io::handle | error);

Creates a new file with the given mode if it doesn't already exist, and opens it for writing.

fn create_file[link]

fn create_file(fs: *fs, path: str, mode: mode, flags: flag = flag::WRONLY | flag::TRUNC) (io::file | error);

Creates a new file with the given mode if it doesn't already exist, and opens it as an io::file 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).

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(dirents: []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 fchmod[link]

fn fchmod(fs: *fs, fd: io::file, mode: mode) (void | error);

Changes mode flags on a io::file.

fn fchown[link]

fn fchown(fs: *fs, fd: io::file, uid: uint, gid: uint) (void | error);

Changes ownership of a io::file.

fn fchtimes[link]

fn fchtimes(fs: *fs, fd: io::file, atime: (time::instant | void), mtime: (time::instant | void)) (void | error);

Changes the access and modification time of an io::file. A void value will leave the corresponding time unchanged.

fn finish[link]

fn finish(iter: *iterator) void;

Frees state associated with an iterator.

fn fstat[link]

fn fstat(fs: *fs, fd: io::file) (filestat | error);

Obtains information about an io::file.

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[link]

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. The return value must be finished with finish.

fn link[link]

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, mode: mode) (void | error);

Creates a directory.

fn mkdirs[link]

fn mkdirs(fs: *fs, path: str, mode: mode) (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 | done | error);

Returns the next directory entry from an iterator, or done if none remain. '.' and '..' are skipped. It is a programming error to call this again after it has returned void. Calling this again after an error is safe. The list is not guaranteed to be complete when an error has been returned. 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: flag = flag::RDONLY) (io::handle | error);

Opens a file.

flag::CREATE isn't very useful with this function, since the new file's mode is set to zero. For this use-case, use create instead.

fn open_file[link]

fn open_file(fs: *fs, path: str, flags: flag = flag::RDONLY) (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).

flag::CREATE isn't very useful with this function, since the new file's mode is set to zero. For this use-case, use create_file instead.

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[link]

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[link]

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

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