System & concurrency
Simple functions for paths, files, environment variables, processes, and system information.
#include <mc/system.h>Path operations use the host filesystem conventions. Durations are in seconds unless a signature takes a std::chrono::duration; memory and file sizes are in bytes unless named otherwise.
Link Catalyst::Shared or Catalyst::Static for the compiled helpers. CTempFile and CTempDir remove owned resources on destruction; CSBuffer requires explicit closure.
enum class CFileType { Missing, File, Directory, Symlink, Other };cstr cJoinPath(std::initializer_list<cstr> parts);cstr cJoinPath(const cstr& first, const cstr& second);template<class... Parts> requires(sizeof...(Parts) > 0) cstr cJoinPath(const cstr& first, const cstr& second, const Parts&... rest);Joins path components with filesystem path semantics; an absolute component can replace the preceding path.
Resolves a relative path against base, or the current directory when base is empty.
Normalizes . and .. lexically without requiring the path to exist.
Returns a lexical path from base to path, making both absolute first. An empty base uses the current directory; symbolic links are not resolved.
Resolves the existing path, including symbolic links.
Expands supported environment syntax and a leading home-directory marker.
bool cHasEnv(const cstr& name);Tests whether the process environment contains the variable, including one set to an empty string.
Returns the environment value. A missing variable gives an empty string, or the explicit fallback in the two-argument overload.
void cUnsetEnv(const cstr& name);Removes a variable from the current process environment. It does not change the parent shell’s environment.
Expands $NAME, ${NAME}, or $(NAME) once. A backslash escapes a dollar. Missing variables throw unless strict=false, which leaves them intact.
Writes the string’s bytes, replacing any existing file contents. Embedded NUL bytes are preserved.
Appends the string’s bytes, creating the file if necessary. No separator or newline is added automatically.
Reads the complete file into an owning CBuffer. The returned bytes remain valid independently of the file.
Reads lines into a vector, removing LF and any immediately preceding CR. Blank lines are retained, and a final unterminated line is included; use cForEachLine() to avoid loading all lines at once.
Visits lines without LF or a preceding CR; return false to stop reading.
void cSaveAtomic(const cstr& text, const cstr& path);void cSaveAtomic(const CBuffer& buffer, const cstr& path);Writes through a temporary sibling and atomically replaces the destination. The parent directory must exist.
bool cCreateDirs(const cstr& path);Creates missing directories throughout the path. Returns true if creation occurred, or false if the directory already existed.
Copies a file’s contents to the destination. An existing destination is rejected unless overwrite is true; use cCopyTree() for directories.
Copies directory contents into the destination. Merges existing directories and preserves symlinks without following them; overwrite applies to leaf entries.
bool cRemove(const cstr& path);Removes a file or empty directory; returns false when it does not exist.
uint64_t cRemoveTree(const cstr& path);Removes an entire tree and returns the number of removed entries.
Returns metadata for a link itself unless followSymlinks=true. writeTime is Unix seconds and permissions holds POSIX permission bits.
bool cIsSymlink(const cstr& path);Tests the directory entry itself for a symbolic link, including a link whose target is missing.
Returns the target text stored in a symbolic link. A relative target remains relative to the directory containing that link.
Creates a link at path containing the supplied target. The target may be relative and need not already exist.
void cWalkDir(const cstr& root, const std::function<bool(const cstr&, const CFileInfo&)>& visit, const CWalkOptions& options = {});Visits entries below the root; false stops the entire walk. When following links, each physical directory is traversed at most once.
CVector<cstr> cFindFiles(const cstr& root, const cstr& pattern = "*", const CWalkOptions& options = {});Matches basenames with *, ?, and bracket patterns; returns sorted paths.
cstr cUserHome();Returns the current user’s home directory. Uses an absolute HOME environment value when available, otherwise the account’s home directory made absolute.
cstr cTempDir();Returns the resolved system temporary-directory path. This locates the shared temporary directory; use cCreateTempDir() to create a new owned directory.
cstr cExecutablePath();Returns the resolved path of the running executable, including symbolic-link resolution.
Returns the user configuration location, optionally with one application-name component appended. Uses ~/Library/Application Support on macOS and an absolute XDG_CONFIG_HOME or ~/.config elsewhere; the directory is not created.
Returns the user cache location, optionally with one application-name component appended. Uses ~/Library/Caches on macOS and an absolute XDG_CACHE_HOME or ~/.cache elsewhere; the directory is not created.
Returns the user data location, optionally with one application-name component appended. Uses ~/Library/Application Support on macOS and an absolute XDG_DATA_HOME or ~/.local/share elsewhere; the directory is not created.
Creates an owned file with mode 0600. An empty directory selects cTempDir().
Creates an owned directory with mode 0700. An empty directory selects cTempDir().
CRunResult cRun(const CVector<cstr>& arguments, const cstr& input = "");Executes an argument vector directly, supplies stdin, and captures both output streams. Nonzero exit status is returned; launch and I/O failures throw.
CRunResult cRunShell(const cstr& command, const cstr& input = "");Runs a shell command, supplies stdin, and captures stdout and stderr. Shell quoting and expansion apply.
Searches for an executable and returns an empty string if none is found.
inline double cMonotonicNow();Returns monotonic seconds for measuring intervals; the origin has no calendar meaning.
inline double cElapsed(double start);Returns seconds elapsed since a cMonotonicNow() reading.
cstr cHostName();Returns the operating system’s complete hostname. Unlike the legacy cHost() helper, it preserves punctuation and domain components.
CDiskSpace cDiskSpace(const cstr& path = ".");Returns filesystem capacity, free bytes, and bytes available to the current user for the given path. Reserved filesystem space can make available smaller than free.
CProcessMemory cProcessMemory();Returns a snapshot of this process’s resident and virtual memory sizes in bytes. These measure different aspects of memory use and need not track one another.
uint64_t cAvailableMemory();Estimates system memory available for use, including reclaimable memory where the platform reports it. This is a changing snapshot, not a guarantee that an allocation will succeed.
inline cstr cHost();Returns the initial alphanumeric part of the hostname. Use cHostName() for the full hostname.
Sets a variable in the process environment. With redefine=false, an existing value is retained; changes do not update the parent shell.
inline size_t cProcessId();Returns the current process ID.
inline size_t cSystemMemory();Returns the system’s physical memory size in bytes using the reported page count and page size.
inline void cReplaceEnvs(cstr& s);Legacy in-place expansion of $(NAME). A missing variable is left in place with a warning.
inline bool cExists(const cstr& path);Tests whether the path resolves to an existing filesystem object. Follows symbolic links, so a dangling link reports false.
inline bool cIsDir(const cstr& path);Tests whether the path resolves to a directory, following symbolic links.
inline bool cIsFile(const cstr& path);Tests whether the path resolves to a regular file, following symbolic links.
Returns the final path component, including its extension.
Returns the final component without its extension.
Returns the lexical parent portion of a path. A bare filename has an empty parent; this does not inspect the filesystem.
Returns the final filename extension without its leading dot, or an empty string if none exists.
inline double cWriteTime(const cstr& path);Returns the last modification time as approximate Unix seconds, converted from the filesystem clock.
inline cstr cCurrentDir();Returns the process’s current working directory.
Returns the names of all immediate directory entries, including hidden entries and subdirectories. Results are not sorted.
inline size_t cFileSize(const cstr& path);Returns a regular file’s size in bytes. This does not recursively total directory contents.
inline bool cReadable(const cstr& path);Tests read access using the current process credentials. It is a preliminary snapshot; a later open can still fail.
inline bool cWritable(const cstr& path);Tests write access using the current process credentials. It does not create the path or ensure a later write will succeed.
inline bool cExecutable(const cstr& path);Tests execute access using the current process credentials. On directories, this tests search permission rather than identifying a runnable program.
Produces a temporary-looking path string; it does not create or reserve the path.
inline double cNow();Returns Unix wall-clock seconds.
inline uint64_t cTicks();Returns the high-resolution clock’s native tick count; do not assume seconds or nanoseconds.
template<class R, class P> inline void cSleep(const std::chrono::duration<R, P>& dt);inline void cSleep(double dt);inline void cSleep();Blocks the current thread for the supplied duration. The numeric overload uses seconds; scheduling may delay the thread beyond the requested interval.
Reads the complete file into a string, preserving its bytes and line endings. Throws CError when the file cannot be opened or read.
inline void cCreateDir(const cstr& path);Creates one directory and throws if creation fails, including when it already exists. cCreateDirs() creates missing parents and tolerates existing directories.
Renames or moves a filesystem entry using the platform’s rename semantics. Cross-filesystem moves can fail; this is not a copy-and-delete operation.
inline size_t cThreadCount();Returns the hardware concurrency hint, which can be zero if unavailable. This is not a count of currently running process threads.
inline cstr cUId();Produces a clock-derived printable identifier; uniqueness is not guaranteed across processes.
inline void cPause();Prints the process ID and sleeps for 30 seconds.
inline void cSaveBinary(char* buf, size_t bytes, const cstr& path);Writes exactly the supplied byte range to a file, replacing existing contents. The caller retains ownership of the source memory.
struct CFileInfostruct CWalkOptionsbool recursive = true;bool followSymlinks = false;class CTempFileDefault construction creates an empty owner; use cCreateTempFile() to create the resource. Move construction transfers cleanup responsibility and leaves the source empty.
Move assignment first attempts to remove the currently owned file, then takes ownership from the source. Cleanup failures are suppressed because the operation is noexcept.
~CTempFile();Attempts to remove the owned file without throwing. Call remove() explicitly when cleanup failures must be reported.
const cstr& path() const;Borrows the owned resource’s absolute path. It is empty after default construction, a move, release, or successful removal.
cstr release();Relinquishes ownership and returns the path. The caller becomes responsible for removal.
void remove();Removes the owned resource now and clears ownership.
class CTempDirDefault construction creates an empty owner; use cCreateTempDir() to create the resource. Move construction transfers cleanup responsibility and leaves the source empty.
Move assignment first attempts to remove the currently owned directory tree, then takes ownership from the source. Cleanup failures are suppressed because the operation is noexcept.
~CTempDir();Attempts to remove the owned directory tree without throwing. Call remove() explicitly when cleanup failures must be reported.
const cstr& path() const;Borrows the owned resource’s absolute path. It is empty after default construction, a move, release, or successful removal.
cstr release();Relinquishes ownership and returns the path. The caller becomes responsible for removal.
void remove();Removes the owned resource now and clears ownership.
struct CRunResultstruct CDiskSpaceuint64_t capacity = 0;uint64_t free = 0;uint64_t available = 0;struct CProcessMemoryuint64_t resident = 0;uint64_t virtualBytes = 0;class CSBuffertemplate<CString T> void create(T&& path, size_t bytes);Creates or resizes a shared backing file and maps the requested nonzero byte count read/write.
template<CString T> void open(T&& path, size_t bytes);Maps an existing backing file, which must contain at least the requested bytes.
void close();Unmaps the region. Copies are non-owning aliases: call once per mapping, after all aliases finish. Destruction does not close it.
const cstr& path() const;Borrows the backing shared-memory name used by this mapping.
unsigned char* buffer() const;Returns a borrowed writable pointer to the mapped bytes. All copies alias the same mapping; stop using them before close() unmaps it.
size_t bytes() const;Returns the size of the shared-memory mapping in bytes.