os +linux +x86_64

The os module provides access to resources from the host operating system, particularly to the filesystem and standard I/O. cwd provides an implementation of fs::fs which is backed by the host filesystem, and this module provides equivalents of various fs functions which infer the current working directory as the fs parameter. This module also provides various non-filesystem related features from the host, such as the hostname, environment variables, and so on.




type amode;
type mcl;
type resolve_flags;


const BUFSIZ: size;


let args: []str;
let cwd: *fs::fs;
let stderr: io::file;
let stdin: io::handle;
let stdin_file: io::file;
let stdout: io::handle;
let stdout_file: io::file;


fn access(str, amode) (bool | fs::error);
fn chdir((*fs::fs | str)) (void | fs::error);
fn chmod(str, fs::mode) (void | fs::error);
fn chown(str, uint, uint) (void | fs::error);
fn chroot(str) (void | fs::error);
fn create(str, fs::mode, fs::flags...) (io::file | fs::error);
fn dirfdfs_set_getdents_bufsz(*fs::fs, size) void;
fn dirfdopen(io::file, resolve_flags...) *fs::fs;
fn dirfile(*fs::fs) io::file;
fn dirfs_clone(*fs::fs, resolve_flags...) *fs::fs;
fn diropen(str) (*fs::fs | fs::error);
fn exit(int) void;
fn finish(*fs::iterator) void;
fn getcwd() str;
fn getenv(const str) (str | void);
fn getenvs() []str;
fn hostname() const str;
fn iter(str) (*fs::iterator | fs::error);
fn machine() const str;
fn mkblk(str, fs::mode, uint, uint) (void | fs::error);
fn mkchr(str, fs::mode, uint, uint) (void | fs::error);
fn mkdir(str, fs::mode) (void | fs::error);
fn mkdirs(str, fs::mode) (void | fs::error);
fn mkfifo(str, fs::mode) (void | fs::error);
fn mlock(*void, size, mcl) (void | errors::error);
fn mlockall(mcl) (void | errors::error);
fn move(str, str) (void | fs::error);
fn munlock(*void, size) (void | errors::error);
fn munlockall() (void | errors::error);
fn open(str, fs::flags...) (io::file | fs::error);
fn readdir(str) ([]fs::dirent | fs::error);
fn readlink(str) (str | fs::error);
fn realpath(str) (str | fs::error);
fn release() const str;
fn remove(str) (void | fs::error);
fn rename(str, str) (void | fs::error);
fn resolve(str) str;
fn rmdir(str) (void | fs::error);
fn rmdirall(str) (void | fs::error);
fn stat(str) (fs::filestat | fs::error);
fn sysname() const str;
fn tryenv(const str, str) str;
fn version() const str;

// Undocumented functions:
fn init_cwd() void;


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

type mcl = enum uint {
	FUTURE = 2,


Flags for the mlock family of operations.

type resolve_flags[link]

type resolve_flags = enum {
	// 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, // 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, 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.

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.


def BUFSIZ[link]

def BUFSIZ: size;

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::file;

The standard error.

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

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

Creates a new file and opens it for writing.

If no flags are provided, fs::flags::WRONLY is used when opening the file.

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

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: resolve_flags...) *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: resolve_flags...) *fs::fs;

Clones a dirfd filesystem, optionally adding additional resolve_flags constraints.

fn diropen[link]

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

Opens a directory as a filesystem.

fn exit[link]

@noreturn fn exit(status: int) void;

Exit the program with the provided status code.

fn finish[link]

fn finish(iter: *fs::iterator) void;

Frees state associated with a directory iterator.

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

fn machine() const str;

Returns the host CPU architecture

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

fn mlock(addr: *void, 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: *void, 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::flags...) (io::file | fs::error);

Opens a file.

If no flags are provided, fs::flags::RDONLY is used when opening the file.

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

fn version() const str;

Returns the host operating system version

fn init_cwd[link]

Show undocumented member
fn init_cwd() void;