This page lists the public API exposed by the os module. The module lives in the vix::os namespace and provides small, portable helpers for reading platform information, user and process information, common directories, basic system resources, and simple blocking sleep delays.

For normal application code, include the public OS header:

#include <vix/os.hpp>

For examples that print values, include the Vix print API:

#include <vix/print.hpp>

All OS module APIs are available under:

namespace vix::os

Most OS functions return vix::error::Result<T>. The module defines a few aliases to keep the function signatures readable.

using StringResult = vix::error::Result<std::string>;
using BoolResult   = vix::error::Result<bool>;
using IntResult    = vix::error::Result<int>;
using UIntResult   = vix::error::Result<unsigned int>;
using SizeResult   = vix::error::Result<std::size_t>;

These aliases do not introduce a different error model. They are only named forms of Result<T> for common OS return types.

[[nodiscard]] StringResult platform();

Returns the current platform name.

Typical values are:

linux
windows
macos
freebsd
unknown

unknown is a valid successful value. It means the platform was not recognized by the current compile-time checks.

auto result = vix::os::platform();

if (result.ok())
  vix::print("platform:", result.value());

[[nodiscard]] StringResult arch();

Returns the current CPU architecture name.

Typical values are:

x86_64
x86
arm64
arm
riscv64
riscv32
unknown

The value is useful for diagnostics and broad runtime decisions. It should not be treated as a complete CPU feature detector.

auto result = vix::os::arch();

if (result.ok())
  vix::print("architecture:", result.value());

[[nodiscard]] StringResult kernel_version();

Returns the current kernel or operating system version string when the platform supports the query.

auto result = vix::os::kernel_version();

if (result.ok())
  vix::print("kernel:", result.value());
else
  vix::eprint("kernel version unavailable:", result.error().message());

This function can fail with NotSupported when the current platform is not supported by the implementation.

[[nodiscard]] StringResult hostname();

Returns the current machine hostname.

auto result = vix::os::hostname();

if (result.ok())
  vix::print("hostname:", result.value());

The hostname is mainly useful for diagnostics, startup output, and local tools that need to identify where a process is running.

[[nodiscard]] IntResult current_pid();

Returns the current process ID.

auto result = vix::os::current_pid();

if (result.ok())
  vix::print("pid:", result.value());

[[nodiscard]] vix::error::Result<UserInfo> current_user();

Returns basic information about the current user.

auto result = vix::os::current_user();

if (result.ok())
{
  const auto &user = result.value();

  vix::print("username:", user.username);
  vix::print("home:", user.home_dir);

  if (!user.shell.empty())
    vix::print("shell:", user.shell);
}

The returned value is a UserInfo structure.

struct UserInfo
{
  std::string username;
  std::string home_dir;
  std::string shell;
};

The shell field depends on the platform and runtime environment. Code that uses it should allow it to be empty.

[[nodiscard]] BoolResult is_admin();

Checks whether the current process is running with administrative privileges.

auto result = vix::os::is_admin();

if (result.ok())
  vix::print("admin:", result.value());

On Unix-like systems, this checks whether the effective user ID is 0. On Windows, it checks whether the current token belongs to the Administrators group.

[[nodiscard]] StringResult home_dir();

Returns the current user’s home directory.

auto result = vix::os::home_dir();

if (result.ok())
  vix::print("home:", result.value());
else
  vix::eprint("home directory unavailable:", result.error().message());

The function may use environment variables or user account information depending on the platform.

[[nodiscard]] StringResult temp_dir();

Returns the system temporary directory.

auto result = vix::os::temp_dir();

if (result.ok())
  vix::print("temp:", result.value());

On Unix-like systems, the function checks common temporary directory environment variables and can fall back to /tmp. On Windows, it uses the platform temporary path API.

[[nodiscard]] UIntResult cpu_count();

Returns the number of available logical CPUs.

auto result = vix::os::cpu_count();

if (result.ok())
  vix::print("logical cpus:", result.value());

The result is useful as a default for worker counts and diagnostics, but application configuration should still be allowed to override it when the workload requires a different value.

[[nodiscard]] SizeResult page_size();

Returns the system memory page size in bytes.

auto result = vix::os::page_size();

if (result.ok())
  vix::print("page size:", result.value(), "bytes");

This value is mostly useful in lower-level memory work, runtime diagnostics, and system-aware tools.

[[nodiscard]] vix::error::Result<std::uint64_t> uptime();

Returns the system uptime in seconds when supported.

auto result = vix::os::uptime();

if (result.ok())
  vix::print("uptime:", result.value(), "seconds");
else
  vix::eprint("uptime unavailable:", result.error().message());

This function can fail when the platform does not support the query through the current implementation.

void sleep_for_ms(std::uint64_t milliseconds);

Blocks the current thread for the given number of milliseconds.

vix::print("waiting");
vix::os::sleep_for_ms(500);
vix::print("done");

void sleep_for_seconds(std::uint64_t seconds);

Blocks the current thread for the given number of seconds.

vix::print("waiting before retry");
vix::os::sleep_for_seconds(1);
vix::print("retrying");

The sleep helpers do not return Result values. They are simple blocking delays built on the standard C++ thread facilities.

struct OsInfo
{
  std::string platform;
  std::string architecture;
  std::string kernel_version;
  std::string hostname;
};

Represents basic operating system identity information.

The structure is available as a public type, but the current public function set shown in this module exposes the individual queries directly through platform(), arch(), kernel_version(), and hostname().

struct UserInfo
{
  std::string username;
  std::string home_dir;
  std::string shell;
};

Represents basic information about the current user.

This structure is returned by current_user().

struct CpuInfo
{
  std::string model;
  std::uint32_t cores{0};
  std::uint32_t threads{0};
};

Represents basic CPU information.

The structure is part of the public OS type set. The current resource query exposed by the module for CPU availability is cpu_count().

struct MemoryInfo
{
  std::uint64_t total_bytes{0};
  std::uint64_t available_bytes{0};
};

Represents basic system memory information.

The structure is part of the public OS type set. The current public resource helpers shown here do not expose a direct memory_info() query.

enum class OsErrorCode
{
  None = 0,
  Unsupported,
  SystemCallFailed,
  PermissionDenied,
  NotFound,
  InvalidArgument,
  Unknown
};

Represents semantic OS-level error cases before they are mapped into the generic Vix error model.

[[nodiscard]] inline constexpr vix::error::ErrorCategory
os_error_category() noexcept;

Returns the OS module error category.

auto category = vix::os::os_error_category();

The category name is os.

[[nodiscard]] inline constexpr vix::error::ErrorCode
to_error_code(OsErrorCode code) noexcept;

Converts an OsErrorCode to the generic vix::error::ErrorCode.

[[nodiscard]] inline const char *to_string(OsErrorCode code) noexcept;

Converts an OsErrorCode to a stable symbolic string.

auto name = vix::os::to_string(vix::os::OsErrorCode::SystemCallFailed);

vix::print("os error:", name);

Typical returned values include:

none
unsupported
system_call_failed
permission_denied
not_found
invalid_argument
unknown

[[nodiscard]] inline vix::error::Error
make_os_error(OsErrorCode code, std::string message);

Creates a structured vix::error::Error for the OS module.

auto error = vix::os::make_os_error(
  vix::os::OsErrorCode::SystemCallFailed,
  "failed to query hostname"
);

This helper is mostly useful inside OS module implementations and tests. Application code usually receives these errors from public OS functions.

Use the topic pages when you need more explanation around a specific group of APIs:

• Platform and Architecture
• User and Process
• Directories
• System Resources
• Sleep
• Errors