StormByte-System 3.0.0
C++26 process and environment module of the StormByte suite
Loading...
Searching...
No Matches
StormByte-System

Multiplatform C++26 CMake License: LGPL v3 or commercial CI Sponsor

StormByte-System is the C++26 process, device and host module of the StormByte suite.

Spawn children with piped stdin/stdout/stderr, classify the medium behind a path, resolve directories and the current executable, inspect the machine, name the calling thread, and expand environment strings. POSIX and Windows stay behind one API. Failures are StormByte::Error::Fault in a per-type domain (StormByte.System.*). Nothing in this module throws.

Table of Contents

Repository

Installation

git clone --recursive https://github.com/StormByte-Suite/StormByte-System.git
cd StormByte-System
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
cmake --install build

Needs a C++26 compiler, CMake 3.28 or newer, StormByte-BuildMaster >= 2.1.4, and StormByte Base 3.0.0. Configure downloads the matching Base release archive. There is no Base submodule. BuildMaster is the installed package when it is >= 2.1.4, otherwise the buildmaster submodule.

Manual builds use the compiler and CMake defaults for optimization and CPU selection; set CMAKE_C_FLAGS / CMAKE_CXX_FLAGS or CFLAGS / CXXFLAGS to choose a CPU baseline. Existing build directories may retain Release flags cached by an older version; configure a fresh build directory to discard them. ENABLE_LTO defaults to ON and can be disabled with -DENABLE_LTO=OFF. CI and releases select cpu-baseline: auto through the build action.

Shared vs static follows CMake BUILD_SHARED_LIBS (declared in lib/, default ON). A plain configure builds the shared library. -DBUILD_SHARED_LIBS=OFF builds a static archive; on Windows the headers then do not use dllimport. The downloaded Base archive is the same mode.

A shared build keeps this library as its own .so / .dll. Under the LGPL that is usually the simpler way to ship: the user can replace that file. A static archive is folded into your binary. The LGPL still applies to this code; you must give the recipient a way to relink your product with a different build of this library. If that does not fit how you distribute the final product, a commercial license is available from the copyright holder (see License).

For installed Base and System prefixes, add Base's share/cmake/Modules to CMAKE_MODULE_PATH and both prefixes to CMAKE_PREFIX_PATH, then use the component finder:

find_package(StormByte REQUIRED COMPONENTS Base System)
target_link_libraries(app PRIVATE StormByte::System)

System installs FindStormByteSystem.cmake in share/cmake/Modules.

Why StormByte-System

Goal How it is achieved
One process API Process starts on construct; pipes are private. Errors are Fault(), not exceptions.
Shell-like chaining p1 >> p2 forwards stdout to stdin on a worker thread.
stdin control << writes a string_view; << System::EoF closes the write end.
Medium behind a path Device probes Kind, Access, nominal Throughput and a suggested Window on demand.
This process on disk Directory and File resolve cwd, home, temp and the running image.
This machine Host reports name, OS, kernel, CPU, ISA, RAM and bitness.
This thread ThisThread::Sleep and Name (reject, do not truncate, if too long).
Environment text Variable::Expand (VAR% on Windows, ~ on UNIX).

Features

  • Move-only Process (fork/exec or CreateProcessW)
  • Piped stdin, stdout, stderr; chaining; Wait / timed Wait; Suspend / Resume
  • Device classification (HDD, SSD, NVMe generations, USB, Network)
  • Directory / File locations of this process
  • Host identity and capacity
  • ThisThread sleep and name
  • Variable::Expand
  • Private Pipe (pipe2 / CreatePipe)
  • Dual license on original sources

Dependencies

Dependency Role
StormByte Base 3.0.0 Error/Fault, visibility, ByteSize, safe text across the DLL boundary
StormByte-BuildMaster >= 2.1.4 Downloads that Base archive and builds this module

The rest of the suite

Module Role API
Base Exceptions, Expected, serialization, UUID, concepts, safe text and pointers /StormByte
Buffer FIFO, SharedFIFO, Ring, Producer/Consumer and multi-stage pipelines /StormByte-Buffer
Config Human-readable text and versioned binary documents /StormByte-Config
Crypto Hash, compress, encrypt, sign and key agreement /StormByte-Crypto
Database One API over SQLite, PostgreSQL and MariaDB /StormByte-Database
Logger Stream logger with levels, headers and redaction /StormByte-Logger
Multimedia Decode, encode and containers without raw FFmpeg types /StormByte-Multimedia
Network Framed packets, Client/Server, IPv4/IPv6 TCP /StormByte-Network
System This repository /StormByte-System

Public API

Name Role
Process Spawn and talk to a child. One public constructor: string_view plus Safe::Vector<Safe::String>. A literal binds; a Safe::String binds through its view conversion. operator bool is true only while the child is live. Pid() exposes only its scalar process ID; native process/thread handles stay private to the owner. Fault() is StormByte.System.Process.
Device Medium behind a path. operator bool is probe success, not permission. Fault() is StormByte.System.Device. Throughput is a nominal rate. Window is a suggested transfer size. Both are ByteSize.
Directory Current, Home, Temporary, CurrentExecutable. bool + out String. LastError() is TLS in this module.
File Temporary(prefix, suffix) (caller unlinks) and CurrentExecutable. Same bool + LastError contract.
Host Name, OS, Kernel, PageSize, PhysicalMemory, AvailableMemory; query objects CPU and Motherboard. Sizes are ByteSize.
Host::CPU Model, Manufacturer, Architecture, PhysicalCores, LogicalProcessors, Bitness.
Host::Motherboard Firmware Manufacturer, Model, Revision. Fields may be unavailable independently.
ThisThread Sleep; Name get/set. Set returns false and TooLong if the platform limit is exceeded.
Variable Expand environment strings. One public entry per width (string_view, wstring_view). The result is StormByte::Safe::String.
System::EoF Close process stdin.

Pipe is private. There is no StormByte/system/exception.hxx and no generic StormByte.System error domain.

Examples

Run a process

Process missing("/no/such/stormbyte-tool");
if (!missing) {
if (missing.Fault().code() == make_error_code(Process::Error::ExecutableNotFound))
/* spawn failed */;
}
args.emplace_back("hello");
Process echo("echo", args);
if (!echo)
return;
echo >> out;
if (echo.Wait() != 0)
/* child status */;
if (echo.Fault().code() == make_error_code(Process::Error::AlreadyExited))
/* second Wait */;
reference emplace_back(Args &&... args)
Runs an external program with piped stdin/stdout/stderr.
Definition process.hxx:87

On Windows use a real binary (cmd.exe, where.exe) instead of echo if it is not on PATH the way you expect.

Pipe two processes

producer_args.emplace_back("%s");
producer_args.emplace_back("hello\n");
Process producer("printf", producer_args);
consumer_args.emplace_back("a-z");
consumer_args.emplace_back("A-Z");
Process consumer("tr", consumer_args);
producer >> consumer;
consumer >> out;
producer.Wait();
consumer.Wait();
static constexpr const _EoF EoF
Sentinel used as process << System::EoF to close stdin.
Definition process.hxx:73

Classify a device

#include <filesystem>
StormByte::System::Device root(std::filesystem::path("/"));
if (!root) {
/* BrokenSymlink, DeviceNotFound, Permission, ProbeFailed */
return;
}
auto kind = root.Kind();
auto access = root.Access();
auto rate = root.Throughput();
auto window = root.Window();
Query object for the medium behind a filesystem accessor.
Definition device.hxx:89

On Windows pass std::filesystem::path("C:\\")</tt>. <tt>operator bool</tt> is not “can write”. A special device node is never writable. Symlinks are followed; a dangling link is <tt>BrokenSymlink</tt>. @subsection directories-and-files Directories and files @icode{cpp} #include <StormByte/system/directory.hxx> #include <StormByte/system/file.hxx> StormByte::Safe::String cwd, home, tmpdir, exe_dir, exe, scratch; if (!StormByte::System::Directory::Current(cwd)) /* Directory::LastError() */; StormByte::System::Directory::Home(home); StormByte::System::Directory::Temporary(tmpdir); StormByte::System::Directory::CurrentExecutable(exe_dir); StormByte::System::File::CurrentExecutable(exe); if (StormByte::System::File::Temporary(scratch, "SB", ".tmp")) { /* use scratch; caller unlinks */ } @endicode Windows <tt>File::Temporary</tt> only uses the first three characters of the prefix (<tt>GetTempFileNameW</tt>). The suffix is appended after the generated name. @subsection host Host @icode{cpp} #include <StormByte/system/host.hxx> StormByte::Safe::String hostname; StormByte::System::Host::Name(hostname); auto os = StormByte::System::Host::OS(); // "Gentoo 2.18", "Windows 11", "macOS 15.1" auto kernel = StormByte::System::Host::Kernel(); // "Linux … SMP PREEMPT_DYNAMIC", "NT 10.0.26100", "Darwin …" auto cpu = StormByte::System::Host::CPU(); auto model = cpu.Model(); auto vendor = cpu.Manufacturer(); auto arch = cpu.Architecture(); unsigned cores = cpu.PhysicalCores(); unsigned threads = cpu.LogicalProcessors(); unsigned bits = cpu.Bitness(); auto board = StormByte::System::Host::Motherboard(); auto board_model = board.Model(); if (StormByte::System::Host::LastError()) /* inspect Unavailable, NotSupported, Permission or Failed */; auto page = StormByte::System::Host::PageSize(); auto ram = StormByte::System::Host::PhysicalMemory(); @endicode <tt>CPU</tt> and <tt>Motherboard</tt> are stateless, copyable query objects. Construction does not probe or change <tt>LastError</tt>; accessors query on demand and update it, except <tt>CPU::Bitness</tt>. Read <tt>LastError()</tt> immediately after the accessor of interest. A failed <tt>ByteSize</tt> or count is zero; a failed <tt>String</tt> is empty. <tt>CPU::Bitness</tt> remains the pointer width of the calling process, not the CPU's maximum width. Core/processor counts cover the OS-visible topology rather than the process affinity or a container's quota. On Linux, physical cores are deduplicated by package/core IDs from sysfs; logical processors are online CPUs. On Windows they include all processor groups. Model/vendor describe the first reported processor; heterogeneous systems need not have identical CPUs. Some Linux ARM systems and virtual machines do not expose a textual CPU model; <tt>Model()</tt> then returns an empty string and <tt>Unavailable</tt>. Linux ARM may expose the vendor as a numeric implementer code; a missing vendor on macOS is <tt>Unavailable</tt>, not an inferred value. Motherboard information comes from Linux sysfs DMI, the firmware-populated Windows BIOS registry, or macOS IOKit. macOS <tt>Model</tt> is <tt>board-id</tt>; <tt>Revision</tt> is <tt>NotSupported</tt>. Firmware, VMs, containers and permissions can leave individual properties unavailable. No external commands or additional dependencies are needed. Memory remains in <tt>PhysicalMemory()</tt> / <tt>AvailableMemory()</tt>; there is no duplicate memory object or firmware RAM expansion limit. @subsection calling-thread Calling thread @icode{cpp} #include <StormByte/system/this_thread.hxx> StormByte::System::ThisThread::Sleep(std::chrono::milliseconds(10)); if (!StormByte::System::ThisThread::Name("worker-1")) { /* TooLong or Failed; LastError() */ } StormByte::Safe::String name; StormByte::System::ThisThread::Name(name); @endicode On Linux/macOS the pthread name limit is 15 characters. Windows <tt>SetThreadDescription</tt> does not use that limit. @subsection expand-variables Expand variables @icode{cpp} #include <StormByte/system/variable.hxx> auto home = StormByte::System::Variable::Expand("~"); auto tmp = StormByte::System::Variable::Expand("TEMP%"); @endicode A literal binds. A <tt>Safe::String</tt> binds through its view conversion. A failed Windows expand returns the original text (same idea as a missing UNIX <tt>\$HOME</tt>). @section design-notes Design notes - <tt>Process</tt> construction starts the child immediately and does not throw. <tt>operator bool</tt> is live status only. - The public <tt>Process</tt> constructor and <tt>operator\<\<</tt> take <tt>std::string_view</tt>. A literal binds. A <tt>Safe::String</tt> binds through its view conversion. The view is copied into Base-owned text before it crosses the DLL boundary. - Windows process and thread handles remain inside <tt>Process</tt> and are closed by <tt>Wait()</tt> or destruction; <tt>Pid()</tt> returns only the child ID. - The private <tt>Process</tt> implementation uses <tt>StormByte::Safe::Unique</tt> and is destroyed by the System module. - Timed <tt>Wait</tt> sets <tt>TimedOut</tt> and leaves the child running. - On UNIX, System ignores <tt>SIGPIPE</tt> once process-wide so a closed pipe peer reports write failure instead of killing the host. - Windows <tt>Suspend()</tt> / <tt>Resume()</tt> snapshot the child threads; a thread created during enumeration may be missed. - Windows stdio handles are made non-inheritable after <tt>CreateProcessW</tt>; a short inheritance window exists during creation. - <tt>Device</tt> stores only the caller accessor. Kind/Access/Throughput/Window are valid only when the Device converts to <tt>true</tt>. Pass a <tt>std::filesystem::path</tt>: a string literal is ambiguous between <tt>Safe::String</tt> and <tt>string_view</tt>. - <tt>Directory</tt> / <tt>File</tt> / <tt>Host</tt> / <tt>ThisThread</tt> <tt>LastError()</tt> is <tt>thread_local</tt> inside this module, exposed by an exported getter. Do not put <tt>thread_local</tt> in a public header. - Public owned text across a DLL boundary is <tt>StormByte::Safe::String</tt> / <tt>StormByte::Safe::WString</tt>. Borrowed views carry explicit lengths; System copies text into module-local NUL-terminated storage when a native API needs a C string. <tt>Process</tt> stdin writes preserve embedded NUL bytes. - Destructor of <tt>Process</tt> waits if the child is still owned. Move invalidates the source. @section testing Testing Enable tests in CMake (<tt>ENABLE_TEST</tt>) and run CTest from the build tree. Process, Device and File tests assert lifecycle and error behavior; Directory, Host and ThisThread also print machine-dependent probe data. Use <tt>ctest -V</tt> to see stdout. @section contributing Contributing Issues and pull requests belong on this repository. Fork and open a PR against <tt>master</tt>. Read @ref "/home/runner/work/StormByte-System/StormByte-System/CONTRIBUTING.md" "CONTRIBUTING.md" before you send a patch (copyright assignment and review rules). Coding rules are in @ref "/home/runner/work/StormByte-System/StormByte-System/CODING_STYLE.md" "CODING_STYLE.md". @section license License Original StormByte-System sources are dual-licensed: GNU Lesser General Public License v3 or later <strong>or</strong> a commercial license from the copyright holder (David C. Manuelda <StormByte@gmail.com>). The grant applies only to original StormByte-System source in this repository. It does not cover other StormByte modules or third-party material shipped here (including everything under <tt>thirdparty/</tt>), which remains under its own license. Neither license grants patent rights. Binary releases add THIRD-PARTY beside LICENSE. That file is a notice for what was compiled into the shared library, not another grant. The texts it names are the COPYING.* files in the same archive. See [LICENSE](LICENSE) for the dual-license notice and <a href="COPYING.LGPLv3" >COPYING.LGPLv3</a> for the full GNU LGPL version 3 text. Also <https://www.gnu.org/licenses/lgpl-3.0.html>. Static linking under the LGPL is described under @ref "installation" "Installation". @section support Support StormByte is developed in spare time. Sponsorship is optional and does not buy features, priority or support. - <a href="https://github.com/sponsors/StormBytePP" >GitHub Sponsors</a> - <a href="https://paypal.me/StormBytePP" >PayPal