os
Python-like operating-system interface, built on std::filesystem. Includes the os.path path-manipulation submodule.
import os
os.getcwd()
os.makedirs("build/cache")
os.path.join("a", "b", "c") # "a/b/c"
os.path.splitext("dir/file.purr") # {"dir/file", ".purr"}Functions
Working directory & process:
getcwd(),chdir(path)— read / change the cwd.getpid(),cpu_count(),system(command)— process id, logical CPU count, run a shell command.urandom(n)—ncryptographically secure random bytes (from the OS CSPRNG).
Directories & files:
listdir(path=".")— entry basenames in a directory.mkdir(path),makedirs(path)— create one / a directory tree.rmdir(path),remove(path),rename(src, dst)— remove / move entries.
Environment:
getenv(name, fallback=""),setenv(name, value, overwrite=true).
os.path submodule:
join(first, ...)— join components with the platform separator.exists(p),isfile(p),isdir(p)— path predicates.basename(p),dirname(p),abspath(p),normpath(p)— path components.getsize(p)— file size in bytes.splitext(p)— split into{root, extension}.
Per-function docs (parameters, runtime complexity, heap behavior) are in os.hpp. Tested in ../tests/os_test.cpp; ASan + Valgrind clean via the QA gate (security/run-valgrind.sh).
Functions
Current working directory.
Queries the process's current directory via std::filesystem::current_path and returns it as an absolute path string.
the absolute cwd.
O(n) + a syscall.
allocates the result string.
CheatahOs.CwdAndCpuCountOsCompileRun.GetcwdStdlibE2E.OsChange the working directory.
Sets the process's current directory; subsequent relative paths resolve against it. Throws if path does not exist or is not a directory.
path | the target directory. |
O(1) + a syscall.
none.
CheatahOs.MakedirsAndChdirOsCompileRun.ChdirStdlibE2E.OsList a directory's entries (basenames only).
Iterates path and returns each entry's filename component (not a full path), in unspecified order; . and .. are not included. Throws if path does not exist or is not a directory.
path | the directory (default |
the entry names.
O(entries) + syscalls.
allocates a vector of strings.
CheatahOs.ListdirAndRenameOsCompileRun.ListdirStdlibE2E.OsCreate a single directory.
Creates the leaf directory only; the parent must already exist (use makedirs to create missing parents). Does nothing if path already exists as a directory.
path | the directory to create. |
O(1) + a syscall.
none.
CheatahOs.MakeDirExistsThenRemoveOsCompileRun.MkdirStdlibE2E.OsCreate a directory and any missing parents.
Creates path along with every intermediate directory that does not yet exist. Succeeds without error if the full path already exists as a directory.
path | the nested directory to create. |
O(depth) + syscalls.
none.
CheatahOs.MakedirsAndChdirOsCompileRun.MakedirsStdlibE2E.Os SystemApps.IntegrityRemove an (empty) directory.
Deletes a single, empty directory; throws if path is non-empty. A missing path is a no-op (no error). Note this is the same fs::remove used by remove(), so it will also delete a regular file at path.
path | the directory to remove. |
O(1) + a syscall.
none.
CheatahOs.MakeDirExistsThenRemoveOsCompileRun.RmdirStdlibE2E.Os SystemApps.IntegrityRemove a file or empty directory.
Deletes a single file or empty directory and returns whether anything was removed; a missing path returns false rather than throwing. Throws if path is a non-empty directory.
path | the entry to remove. |
true iff something was removed.
O(1) + a syscall.
none.
OsCompileRun.RemoveStdlibE2E.Os SystemApps.EventLog SystemApps.IntegrityRename/move src to dst.
Moves or renames an entry; an existing dst is overwritten when permitted by the underlying fs::rename. Crossing filesystems or other failures throw.
src | source path. |
dst | destination path. |
O(1) + a syscall.
none.
CheatahOs.ListdirAndRenameOsCompileRun.RenameStdlibE2E.OsRead an environment variable.
Returns fallback (default "") when the variable is unset; an empty string result therefore does not distinguish "unset" from "set to empty".
name | the variable name. |
fallback | returned when unset. |
the value, or fallback.
O(environment size) — std::getenv is a linear scan of the C library's environment table (no syscall).
allocates the returned string.
OsCompileRun.GetenvStdlibE2E.OsSet an environment variable.
When overwrite is false and the variable already exists, the existing value is kept; otherwise it is created or replaced. The change affects only this process and its future children.
name | the variable name. |
value | the value to set. |
overwrite | replace an existing value when true. |
O(environment size) — the C library scans and updates its environment table (no syscall).
may allocate inside the C library's environment table.
CheatahOs.SetenvThenGetenvOsCompileRun.SetenvStdlibE2E.OsProcess id.
the current process's pid.
O(1) + a syscall.
none.
CheatahOs.PidAndSystemOsCompileRun.GetpidStdlibE2E.OsLogical CPU count.
Reports std::thread::hardware_concurrency(), the number of concurrent threads supported; the standard allows it to return 0 when the value cannot be determined, so callers should treat 0 as "unknown".
the number of hardware threads (0 if undetermined).
O(1).
none.
CheatahOs.CwdAndCpuCountOsCompileRun.CpuCountStdlibE2E.OsRun a shell command.
Passes command to the system shell via std::system and blocks until it finishes; the returned status is implementation-defined (on POSIX, a wait status, conventionally decoded so that 0 means success).
command | the command line. |
the command's exit status.
O(1) here + the cost of the spawned process (fork/exec via the shell).
none.
command is interpreted by the shell (quoting, expansion, ;/|) — never build it from untrusted input.
CheatahOs.PidAndSystemOsCompileRun.SystemStdlibE2E.OsCryptographically secure random bytes (like Python's os.urandom).
Reads n bytes from the operating system's CSPRNG — getentropy//dev/urandom on POSIX, BCryptGenRandom on Windows — suitable for keys and signatures. Unlike the random module (a deterministic, seedable PRNG), this is NOT reproducible and must not be seeded. Throws std::runtime_error if the OS source cannot be read (so a key is never built from non-random bytes), and std::invalid_argument for a negative n.
n | the number of bytes to return (must be non-negative). |
a string of n random bytes (may contain embedded NULs).
O(n), plus one syscall per 256-byte chunk on POSIX (getentropy's per-call limit; a single BCryptGenRandom call on Windows).
allocates the n-byte result.
CheatahOs.UrandomOsCompileRun.UrandomStdlibE2E.OsThe loadable-module file extension for this platform.
A compiled cheatah program is a native loadable module run by the cheatah host; its file extension is .so on Linux/BSD, .dylib on macOS, and .dll on Windows. Tools that build or name modules (e.g. the biome package manager) use this instead of hardcoding .so, so the paths they print and generate are correct on every platform. The result includes the leading dot.
the platform module extension (e.g. ".so", ".dylib", ".dll").
O(1).
allocates the returned string.
CheatahOs.ModuleExtOsCompileRun.ModuleExtStdlibE2E.Os