os.fs

import os

Everything here is re-exported by os, so import os is enough and the names are called as os.*. Importing os.fs on its own works too and reaches the same definitions.

Directory and filesystem-entry operations: creating, listing, and removing directories, permissions and ownership, symbolic links, searching PATH for an executable, and glob-style pattern matching. Per-file operations (reading, writing, deleting, or copying a single file, or getting its size/mtime/etc.) live on the file class instead: see file.stats(), file.delete(), file.copy(), and friends.

Constants

DT_UNKNOWN

os.DT_UNKNOWN: number

Unknown file type

DT_BLK

os.DT_BLK: number

Block device file type

DT_CHR

os.DT_CHR: number

Character device file type

DT_DIR

os.DT_DIR: number

Directory file type

DT_FIFO

os.DT_FIFO: number

Named pipe file type

DT_LNK

os.DT_LNK: number

Symbolic link file type

DT_REG

os.DT_REG: number

Regular file type

DT_SOCK

os.DT_SOCK: number

Local-domain socket file type

DT_WHT

os.DT_WHT: number

Whiteout file type (only meaningful on UNIX and some unofficial Linux versions).

Note: value is -1 on systems where it is not supported.

Functions

create_dir()

os.create_dir(path: string, permission: ?int, recursive: ?bool) -> boolean

Creates the given directory with the specified permission and optionally add new files into it if any is given.

Parameters

• path (string)
• permission (?int) — Default value is 0c777
• recursive (?bool) — Default value is true.

Returns boolean

Note: if the directory already exists, it returns false otherwise, it returns true.

Note: permission should be given as octal number.

read_dir()

os.read_dir(path: string, recursive: ?bool) -> list[string]

Scans the given directory and returns a list of the names it contains, sorted by name, led by . and ...

Example,

%> os.read_dir('./tests')
[., .., buggy.zu, myprogram.zu, single_thread.zu, test.zu]

When the recursive argument is set to true, sub-directories are descended into as well, and their contents come back as paths relative to path rather than as bare names. A directory’s contents follow immediately after the directory itself, and entries are sorted by name within every level:

%> os.read_dir('./tests', true)
[., .., buggy.zu, data, data/input.csv, test.zu]

A symbolic link to a directory is listed but not descended into, whether or not it points somewhere inside path.

Parameters

• path (string)
• recursive (?bool) — Default is false.

Returns list[string]

Note: . indicates current directory and can be used as argument to os.read_dir as well.

Note: .. indicates parent directory and can be used as argument to os.read_dir as well.

chmod()

os.chmod(path: string, mode: int) -> boolean

Changes the permission set on a directory to the given mode. It is advisable to set the mode with an octal number (e.g. 0c777) as this is consistent with operating system values.

Parameters

• path (string)
• mode (int)

Returns boolean

is_dir()

os.is_dir(path: string) -> bool

Returns true if the path is a directory or false otherwise.

Parameters

• path (string)

Returns bool

remove_dir()

os.remove_dir(path: string, recursive: ?bool) -> bool

Deletes a non-empty directory. If recursive is true, non-empty directories will have their contents deleted first.

Parameters

• path (string)
• recursive (?bool) — Default value is false.

Returns bool

dir_exists()

os.dir_exists(path: string) -> bool

Returns true if path exists and is a directory, false otherwise (including when path exists but is a regular file or some other non-directory entry).

Parameters

• path (string)

Returns bool

rename()

os.rename(old_name: string, new_name: string) -> bool

Renames the file or directory specified by old_name to the name given by new_name.

If old_name and new_name are existing hard links referring to the same file, then it does nothing, and returns a success status.

If old_name specifies a directory, new_name must either not exist, or it must specify an empty directory.

If old_name refers to a symbolic link, the link is renamed; if new_name refers to a symbolic link, the link will be overwritten.

Parameters

• old_name (string)
• new_name (string)

Returns bool

Raises Error

chown()

os.chown(path: string, uid: int, gid: int) -> bool

Changes the owning user and group of path to uid and gid.

Parameters

• path (string)
• uid (int)
• gid (int)

Returns bool

Raises Error

Note: this is a Unix-only operation; ownership isn’t a concept Windows has a direct equivalent for, so this raises there.

umask()

os.umask(mask: ?int) -> int

Gets or sets the process’s file-creation mask: the set of permission bits stripped from every file/directory this process creates from now on.

Called with no argument (or nil), returns the current mask without changing it. Called with a mask, sets it and returns whatever the previous mask was.

Parameters

• mask (?int)

Returns int

Raises Error

Note: this is a Unix-only operation; Windows has no umask concept, and this raises there.

is_symlink()

os.is_symlink(path: string) -> bool

Returns true if path exists and is a symbolic link, false otherwise (including when path doesn’t exist at all).

Parameters

• path (string)

Returns bool

readlink()

os.readlink(path: string) -> string

Returns the target path points to, if path is a symbolic link. Unlike os.real_path(), this reads exactly one link level and doesn’t recursively resolve further: if the target is itself a symlink, its own target is what gets returned, not the final destination.

Parameters

• path (string)

Returns string

Raises Error if path doesn’t exist or isn’t a symbolic link.

which()

os.which(name: string) -> ?string

Searches every directory in the PATH environment variable, in order, for an executable file named name, the same way a shell decides what running a bare command name actually runs. Returns the full path to the first match, or nil if none of them have a matching executable.

Example,

%> os.which('git')
'/usr/bin/git'
%> os.which('does-not-exist')
nil

Parameters

• name (string)

Returns ?string

glob()

os.glob(pattern: string, base_path: ?string) -> list[string]

Returns every entry under base_path (the current working directory if not given) whose path matches the glob pattern.

pattern supports * (anything except a path separator), ? (exactly one character, except a path separator), and a doubled star (anything, including path separators, for matching across nested directories).

Example,

%> os.glob('*.zu')
['helper.zu', 'main.zu']
%> os.glob('lib?.zu')
['libc.zu', 'libz.zu']

Matches are returned in the order read_dir() walks the tree, which means sorted by name within each directory, with a directory’s own matches following it.

Parameters

• pattern (string)
• base_path (?string) — Default is the current working directory.

Returns list[string]

2021, Richard Ore and Zuri contributors