type amode[link]

type amode = enum {
	F_OK = rt::F_OK,
	R_OK = rt::R_OK,
	W_OK = rt::W_OK,
	X_OK = rt::X_OK,
};

Access modes for access.

type arch[link]

type arch = enum {
	AARCH64,
	RISCV64,
	X86_64,
};

All currently supported target architectures. This enum will be extended whenever support for a new architecture is added.

type mcl[link]

type mcl = enum uint {
	CURRENT = 1,
	FUTURE = 2,
	ONFAULT = 4,
};

Flags for the mlock family of operations.

type memfd_flag[link]

type memfd_flag = enum uint {
	NONE = 0,
	NOCLOEXEC = rt::MFD_CLOEXEC, // Unsets the close-on-exec flag when creating a memfd.
	ALLOW_SEALING = rt::MFD_ALLOW_SEALING, // ALlows sealing operations on this file.
	HUGETLB = rt::MFD_HUGETLB, // Create the memfd with huge pages using hugetlbfs. Linux-only.
};

Flags for memfd.

type resolve_flag[link]

type resolve_flag = enum u64 {
	NORMAL = 0,
	// Does not allow symlink resolution to occur for any symlinks which
	// would refer to any anscestor of the fd directory. This disables all
	// absolute symlinks, and any call to open or create with an absolute
	// path.
	BENEATH = rt::RESOLVE_BENEATH | rt::RESOLVE_NO_MAGICLINKS,
	// Treat the directory fd as the root directory. This affects
	// open/create for absolute paths, as well as absolute path resolution
	// of symlinks. The effects are similar to chroot.
	IN_ROOT = rt::RESOLVE_IN_ROOT | rt::RESOLVE_NO_MAGICLINKS,
	NO_SYMLINKS = rt::RESOLVE_NO_SYMLINKS, // Disables symlink resolution entirely.
	// Disallows traversal of mountpoints during path resolution. This is
	// not recommended for general use, as bind mounts are extensively used
	// on many systems.
	NO_XDEV = rt::RESOLVE_NO_XDEV,
};

Controls how symlinks are followed (or not) in a dirfd filesystem. Support for this feature varies, you should gate usage of this enum behind a build tag.

Note that on Linux, specifying BENEATH or IN_ROOT will also disable magic symlinks.

type status[link]

type status = enum {
	SUCCESS = 0,
	FAILURE = 1,
};

Values that may be passed to exit to indicate successful or unsuccessful termination, respectively.

type setxattr_flag[link]

type setxattr_flag = enum {
	NONE = 0,
	XATTR_CREATE = 1,
	XATTR_REPLACE = 2,
};

def BUFSZ[link]

def BUFSZ: size = 4096;

The recommended buffer size for reading from disk.

let args[link]

let args: []str;

The command line arguments provided to the program. By convention, the first member is usually the name of the program.

let cwd[link]

let cwd: *fs::fs;

Provides an implementation of fs::fs for the current working directory.

let stderr[link]

let stderr: io::handle;

The standard error. This handle is unbuffered.

let stderr_file[link]

let stderr_file: io::file;

The standard error, as an io::file. This handle is unbuffered.

let stdin[link]

let stdin: io::handle;

The standard input. This handle is buffered.

let stdin_file[link]

let stdin_file: io::file;

The standard input, as an io::file. This handle is unbuffered.

let stdout[link]

let stdout: io::handle;

The standard output. This handle is buffered.

let stdout_file[link]

let stdout_file: io::file;

The standard output, as an io::file. This handle is unbuffered.

fn access[link]

fn access(path: str, mode: amode) (bool | fs::error);

Returns true if the given mode of access is permissible. The use of this function is discouraged as it can allow for a race condition to occur betwen testing for the desired access mode and actually using the file should the permissions of the file change between these operations. It is recommended instead to attempt to use the file directly and to handle any errors that should occur at that time.

fn arch_name[link]

fn arch_name(arch: arch) const str;

Returns a portable string for an arch.

fn architecture[link]

fn architecture() arch;

Returns the host CPU architecture.

fn chdir[link]

fn chdir(target: (*fs::fs | str)) (void | fs::error);

Change the current working directory.

fn chmod[link]

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

Changes mode flags on a file or directory. Type bits are discared.

fn chown[link]

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

Changes ownership of a file.

fn chroot[link]

fn chroot(target: str) (void | fs::error);

Changes the root directory of the process. Generally requires the caller to have root or otherwise elevated permissions.

This function is not appropriate for sandboxing.

fn chtimes[link]

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

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

fn cpucount[link]

fn cpucount() (size | errors::error);

Returns the number of usable CPUs.

fn create[link]

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

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

Only the permission bits of the mode are used. If other bits are set, they are discarded.

To create a file without opening it, see mkfile.

fn dirfdfs_set_getdents_bufsz[link]

fn dirfdfs_set_getdents_bufsz(fs: *fs::fs, sz: size) void;

Sets the buffer size to use with the getdents(2) system call, for use with fs::iter. A larger buffer requires a larger runtime allocation, but can scan large directories faster. The default buffer size is 32 KiB.

This function is not portable.

fn dirfdopen[link]

fn dirfdopen(fd: io::file, resolve_flags: resolve_flag = resolve_flag::NORMAL) *fs::fs;

Opens a file descriptor as an fs::fs. This file descriptor must be a directory file. The file will be closed when the fs is closed.

fn dirfile[link]

fn dirfile(fs: *fs::fs) io::file;

Returns an io::file for this filesystem. This function is not portable.

fn dirfs_clone[link]

fn dirfs_clone(fs: *fs::fs, resolve_flags: resolve_flag = resolve_flag::NORMAL) *fs::fs;

Clones a dirfd filesystem, optionally adding additional resolve_flag constraints.

fn diropen[link]

fn diropen(path: str) (*fs::fs | fs::error);

Opens a directory as a filesystem.

fn exists[link]

fn exists(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 exit[link]

fn exit(status: int) never;

Exit the program with the provided status code.

fn fchmod[link]

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

Changes mode flags on a io::file. Type bits are discared.

fn fchown[link]

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

Changes ownership of a [io::file]].

fn fchtimes[link]

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

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

fn fstat[link]

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

Returns file information for an io::file.

fn getcwd[link]

fn getcwd() str;

Returns the current working directory. The return value is statically allocated and must be duplicated (see strings::dup) before calling getcwd again.

fn getenv[link]

fn getenv(name: const str) (str | void);

Looks up an environment variable and returns its value, or void if unset.

fn getenvs[link]

fn getenvs() []str;

Returns a slice of the environment strings in the form KEY=VALUE.

fn getfl[link]

fn getfl(file: io::file) (fs::flag | errors::error);

Returns the fs::flags associated with a file descriptor. See fcntl(2).

fn getxattr[link]

fn getxattr(path: str, name: str) ([]u8 | fs::error);

Gets an extended file attribute. The caller is responsible for freeing the returned slice.

fn hostname[link]

fn hostname() const str;

Returns the host system hostname

fn iter[link]

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

Creates an fs::iterator for a given directory to read its contents. The user should call fs::next to enumerate entries, and fs::finish when done using the object.

fn link[link]

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

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

fn machine[link]

fn machine() const str;

Returns the host CPU architecture, in a platform-specific format. See architecture for a more portable wrapper.

fn memfd[link]

fn memfd(name: str, flags: memfd_flag = memfd_flag::NONE) (io::file | errors::error);

Creates a new anonyomous io::file backed by memory.

The initial file size is zero. It can be written to normally, or the size can be set manually with trunc.

This function is available on Linux and FreeBSD.

fn mkblk[link]

fn mkblk(path: str, mode: fs::mode, major: uint, minor: uint) (void | fs::error);

Makes a block device node. This function is only available on Unix-like systems.

fn mkchr[link]

fn mkchr(path: str, mode: fs::mode, major: uint, minor: uint) (void | fs::error);

Makes a character device node. This function is only available on Unix-like systems.

fn mkdir[link]

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

Creates a directory.

fn mkdirs[link]

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

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

fn mkfifo[link]

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

Makes a FIFO node. This function is only available on Unix systems.

fn mkfile[link]

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

Makes a regular file. This function is only available on Unix-like systems. This function should only be used if you have a special reason; most of the time you should use create instead.

fn mlock[link]

fn mlock(addr: *opaque, length: size, flags: mcl) (void | errors::error);

Locks a region of memory so that it will not be written to swap.

fn mlockall[link]

fn mlockall(flags: mcl) (void | errors::error);

Locks the entire process's address space so that it will not be written to swap.

fn move[link]

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

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

fn munlock[link]

fn munlock(addr: *opaque, length: size) (void | errors::error);

Unlocks memory previously locked with mlock.

fn munlockall[link]

fn munlockall() (void | errors::error);

Unlocks all locked memory in the process's address space.

fn open[link]

fn open(path: str, flags: fs::flag = fs::flag::RDONLY) (io::file | fs::error);

Opens a file.

fs::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 readdir[link]

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

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

fn readlink[link]

fn readlink(path: str) (str | fs::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(path: str) (str | fs::error);

Canonicalizes a path in this filesystem by resolving all symlinks and collapsing any "." or ".." path components.

This function is a thin shim over fs::realpath, and the return value is statically allocated by fs::realpath. Thus, calls to this function or to fs::realpath will overwrite the return value of either function.

fn release[link]

fn release() const str;

Returns the host kernel version

fn remove[link]

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

Removes a file.

fn removexattr[link]

fn removexattr(path: str, name: str) (void | fs::error);

Removes an extended file attribute.

fn rename[link]

fn rename(oldpath: str, newpath: str) (void | fs::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(path: str) str;

Resolves a path to its absolute, normalized value. Relative paths will be rooted (if supported by the host filesystem), 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(path: str) (void | fs::error);

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

fn rmdirall[link]

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

Removes a directory, and anything in it.

fn setenv[link]

fn setenv(name: const str, value: const str) (void | errors::invalid);

Sets an environment variable, overwriting it if it's already set. The name may not contain '=' or '\0', and the value may not contain '\0'.

fn setfl[link]

fn setfl(file: io::file, flags: fs::flag) (void | errors::error);

Sets the fs::flags associated with a file descriptor. Changes to the access mode (e.g. fs::flag::RDWR and file creation flags (e.g. fs::flag::CREATE) are ignored. See fcntl(2).

fn setxattr[link]

fn setxattr(path: str, name: str, value: []u8, flags: setxattr_flag = setxattr_flag::NONE) (void | fs::error);

Sets an extended file attribute.

fn shm_open[link]

fn shm_open(name: str, oflag: fs::flag = fs::flag::CREATE | fs::flag::RDWR, mode: fs::mode = 384) (io::file | fs::error);

Opens (or creates, given fs::flag::CREATE) a global shared memory file with the given name, suitable for use with io::mmap to establish shared memory areas with other processes using the same name.

The name must not contain any forward slashes (one is permissible at the start, e.g. "/example") and cannot be "." or "..".

The "oflag" parameter, if provided, must include either fs::flag::RDONLY or fs::flag::RDWR, and may optionally add fs::flag::CREATE, fs::flag::EXCL, and/or fs::flag::TRUNC, other flags are silently ignored if set.

The new file descriptor always has CLOEXEC set regardless of the provided flags. If creating a new shared memory object, set its initial size with io::trunc before mapping it with io::mmap.

Call shm_unlink to remove the global shared memory object.

fn shm_unlink[link]

fn shm_unlink(name: str) (void | fs::error);

Removes the shared memory object with the given name. Processes which already hold a reference to the file may continue to use the memory associated with it. Once all processes have unmapped the associated shared memory object, or exited, the memory is released.

fn stat[link]

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

Returns file information for a given path. If the target is a symlink, information is returned about the link, not its target.

fn symlink[link]

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

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

fn sysname[link]

fn sysname() const str;

Returns the host kernel name

fn tryenv[link]

fn tryenv(name: const str, default: str) str;

Looks up an environment variable and returns its value, or a default value if unset.

fn unsetenv[link]

fn unsetenv(name: const str) (void | errors::invalid);

Unsets an environment variable. Does nothing if the variable isn't set. The name may not contain '=' or '\0'.

fn version[link]

fn version() const str;

Returns the host operating system version