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.
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:
System installs FindStormByteSystem.cmake in share/cmake/Modules.
| 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). |
| 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 |
| 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 |
| 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.
On Windows use a real binary (cmd.exe, where.exe) instead of echo if it is not on PATH the way you expect.
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