From 9fa43fbc37a2b044fb1e384321de91b65d4f4639 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Thu, 19 Nov 2026 11:56:09 +0900 Subject: [PATCH 1/2] 0.23.0: a unit's reference names its boot and its session (openkal 0.26) - the reference (W2) adds the count of boots and the session to the job's name; a reference of another boot is EMPTY - a reference of another session, and one whose name the system dropped with its last handle, are kal_err_not_supported from open, where both were a name that is not there (clause 7.18) - KAL_PROCESS_PROP_JOB_OBSERVE is claimed where the session can be read - openkal ^0.26.0 --- README.md | 25 +++++- mcpp.toml | 4 +- src/process.cpp | 71 ++++++++++++++-- ...t_reference_names_its_boot_and_session.cpp | 84 +++++++++++++++++++ 4 files changed, 170 insertions(+), 14 deletions(-) create mode 100644 tests/a_unit_reference_names_its_boot_and_session.cpp diff --git a/README.md b/README.md index 01f0d78..b644b6a 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ An implementation of [openkal](https://github.com/mcpplibs/openkal) for Windows. ```toml [dependencies] -openkal = "0.25.0" +openkal = "0.26.0" [target.'cfg(windows)'.dependencies] -openkal-windows = "0.22.2" +openkal-windows = "0.23.0" ``` Its purpose is as much to test the specification as to be used. openkal was @@ -15,6 +15,23 @@ drawn against systems that share an ancestry; a third implementation on a system that shares none of it is what turns "this interface is not Unix's shape" from a claim into an observation. +## What 0.23 changes (openkal 0.26) + +**A unit's reference names its boot and its session** (clause 7.18). A unit is a +named job in the session's namespace, and its reference (`W2`) adds the count of +boots the system's loader keeps and the session. A reference of another boot is +`empty`. A reference of another session, and one whose name the system no longer +keeps --- it drops a job's name with its last handle, whether or not a member +remains --- are refused by `kal_process_job_open` with `kal_err_not_supported`: +neither can be opened however long the caller waits, where both were a name that +is not there. A reference in the earlier form (`W1`) is answered by its name as +before. `KAL_PROCESS_PROP_JOB_OBSERVE` is claimed where the session can be read +and two handles compared. `tests/a_unit_reference_names_its_boot_and_session.cpp`. + +**A start is bounded by the system alone** (clause 7.6). This implementation kept +no bound upon the number of arguments or variables; a command line beyond the +32,767 units the system takes is `kal_err_no_space`, as before. + ## What 0.22.2 corrects The manifest declares `openkal = "^0.25.0"`. An implementation written against a @@ -79,7 +96,9 @@ when the count wraps. The process interface provides the OpenKal 0.24 declared-unit operations. Observation retains the original named-job handle and queries its active -membership. A missing name after every handle is lost reports `unknown`. +membership. A name the system dropped with its last handle is refused by +`kal_process_job_open` with `kal_err_not_supported` (0.23.0): it is not evidence +that the members have ended, and it cannot be opened again. Retirement checks the live continuation identity and requires that no external member remains. Closing an observation handle does not terminate the unit. diff --git a/mcpp.toml b/mcpp.toml index d736bf5..09797fb 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "openkal-windows" -version = "0.22.2" +version = "0.23.0" description = "An implementation of openkal for Windows, written on the Win32 interfaces and the object manager beneath them, using no C runtime symbol." license = "Apache-2.0" @@ -67,7 +67,7 @@ provides-interfaces = [ [dependencies] # Every patch release of the specification's minor version (openkal clause 8). -openkal = "^0.25.0" +openkal = "^0.26.0" # The package contributes definitions and no modules. The interface it # implements is declared by the specification package, which this package diff --git a/src/process.cpp b/src/process.cpp index c8535d5..d6708f0 100644 --- a/src/process.cpp +++ b/src/process.cpp @@ -1308,10 +1308,41 @@ using compare_objects_fn = BOOL (OKW_API*)(HANDLE,HANDLE); compare_objects_fn unit_compare() { return reinterpret_cast(okw::system_function(L"kernelbase.dll","CompareObjectHandles")); } -bool observable_units() { return unit_compare() != nullptr; } +// WHAT A REFERENCE NAMES, AND WHAT AN OBSERVATION CAN ESTABLISH (openkal 0.26, +// clause 7.18). A unit is a named job in the session's own namespace +// (`Local\'), so a reference (`W2') names the count of boots and the session +// beside the job's name: +// another boot every program of it has ended EMPTY +// another session its names cannot be opened from here: `open' +// refuses, to this caller always +// this session, no such name +// the system drops a job's name with its last +// handle, whether or not a member remains, so the +// unit can never be opened again: `open' refuses +// this session, the job its count of active processes +// A `W1' reference names neither, and is answered by its name alone. +// +// The count of boots is the word the system's loader advances at each boot +// (KUSER_SHARED_DATA.BootId, at one address in every process). A resume from +// hibernation restores the word with the rest of memory, so it changes only +// where every program has ended. Zero where the word is not kept: the +// reference then names no boot, and none is compared. +kal_u64 unit_boot() { return *reinterpret_cast(static_cast(0x7ffe02c4u)); } +bool unit_session(kal_u64& session) { + DWORD value = 0; + if (!ProcessIdToSessionId(GetCurrentProcessId(),&value)) return false; + session = value; return true; +} +// Claimed where a reference can be made: the session read, the handles compared. +bool observable_units() { kal_u64 session = 0; return unit_compare() != nullptr && unit_session(session); } struct unit_identity { - kal_u64 owner = 0, birth = 0; char name[96]{}; + kal_u64 owner = 0, birth = 0, boot = 0, session = 0; char name[96]{}; + bool exact = false; // a W2 reference, which names its boot and its session }; +bool unit_earlier_boot(const unit_identity& u) { + const kal_u64 boot = unit_boot(); + return u.exact && u.boot != 0 && boot != 0 && u.boot != boot; +} bool unit_birth(kal_u64& birth) { FILETIME created{}, ended{}, kernel{}, user{}; if (!GetProcessTimes(GetCurrentProcess(),&created,&ended,&kernel,&user)) return false; @@ -1321,9 +1352,13 @@ bool unit_birth(kal_u64& birth) { bool unit_parse(const char* p, kal_uintptr n, unit_identity& u) { if (!p || n == 0 || n > 256) return false; unit_reference::reader r{p,n}; char kind[8]{}; - if (!r.token(kind,sizeof kind) || !unit_reference::same(kind,"W1") - || !r.number(u.owner) || !u.owner || !r.number(u.birth) || !u.birth - || !r.token(u.name,sizeof u.name) || r.at != n) return false; + if (!r.token(kind,sizeof kind)) return false; + u.exact = unit_reference::same(kind,"W2"); + if (!u.exact && !unit_reference::same(kind,"W1")) return false; + if (!r.number(u.owner) || !u.owner || !r.number(u.birth) || !u.birth + || !r.token(u.name,sizeof u.name)) return false; + if (u.exact && !(r.number(u.boot) && r.number(u.session))) return false; + if (r.at != n) return false; static const char prefix[] = "Local\\openkal-unit-"; for (kal_uintptr i = 0; i < sizeof prefix - 1; ++i) if (u.name[i] != prefix[i]) return false; kal_uintptr at = sizeof prefix - 1; @@ -1348,9 +1383,10 @@ extern "C" { int kal_process_job_create(kal_job* out, char* reference, kal_uintptr capacity, kal_uintptr* used) { if (!out || !reference || !used) return kal_err_invalid; if (capacity < 256) return kal_err_no_space; - if (!unit_compare()) return kal_err_not_supported; + if (!observable_units()) return kal_err_not_supported; unit_identity u; u.owner = GetCurrentProcessId(); - if (!unit_birth(u.birth)) return kal_err_not_supported; + if (!unit_birth(u.birth) || !unit_session(u.session)) return kal_err_not_supported; + u.boot = unit_boot(); unsigned char random[16]{}; const int random_rc = kal_random_fill(random,sizeof random); if (random_rc != kal_ok) return random_rc; static const char prefix[] = "Local\\openkal-unit-", hex[] = "0123456789abcdef"; @@ -1361,7 +1397,8 @@ int kal_process_job_create(kal_job* out, char* reference, kal_uintptr capacity, SetLastError(0); HANDLE job = CreateJobObjectW(nullptr,name); if (!job) return okw::translate_win32(GetLastError()); if (GetLastError() == 183 /* ERROR_ALREADY_EXISTS */) { CloseHandle(job); return kal_err_again; } - unit_reference::writer w; w.text("W1;"); w.number(u.owner); w.next(); w.number(u.birth); w.next(); w.text(u.name); + unit_reference::writer w; w.text("W2;"); w.number(u.owner); w.next(); w.number(u.birth); w.next(); w.text(u.name); + w.next(); w.number(u.boot); w.next(); w.number(u.session); if (!w.valid) { CloseHandle(job); return kal_err_no_space; } if (!AssignProcessToJobObject(job,GetCurrentProcess())) { const auto error = GetLastError(); CloseHandle(job); return okw::translate_win32(error); } const auto packed = okw::pack(job); @@ -1372,7 +1409,22 @@ int kal_process_job_open(const char* reference, kal_uintptr length, kal_job* out if (!out) return kal_err_invalid; unit_identity u; if (!unit_parse(reference,length,u)) return kal_err_invalid; if (!unit_compare()) return kal_err_not_supported; - HANDLE job = unit_open(u); if (!job) return okw::translate_win32(GetLastError()); + HANDLE job = nullptr; + if (unit_earlier_boot(u)) { + // Nothing of that boot is left to open. The handle stands for the + // reference and is a job of no members; `observe' answers from the + // reference before it reads a handle. + job = CreateJobObjectW(nullptr,nullptr); + if (!job) return okw::translate_win32(GetLastError()); + } else { + kal_u64 session = 0; + if (u.exact && (!unit_session(session) || session != u.session)) return kal_err_not_supported; + job = unit_open(u); + if (!job) { + const DWORD why = GetLastError(); + return why == 2 /* ERROR_FILE_NOT_FOUND */ ? kal_err_not_supported : okw::translate_win32(why); + } + } const auto packed = okw::pack(job); if (!packed) { CloseHandle(job); return kal_err_no_memory; } out->h = packed; return kal_ok; @@ -1381,6 +1433,7 @@ int kal_process_job_observe(kal_job job, const char* reference, kal_uintptr leng if (!state) return kal_err_invalid; *state = KAL_JOB_UNKNOWN; unit_identity u; if (!unit_parse(reference,length,u)) return kal_err_invalid; HANDLE original = okw::unpack(job.h); if (!original) return kal_err_invalid; + if (unit_earlier_boot(u)) { *state = KAL_JOB_EMPTY; return kal_ok; } if (!unit_matches(original,u)) return kal_ok; JOB_ACCOUNTING_ usage{}; if (!QueryInformationJobObject(original,JobObjectBasicAccountingInformation_,&usage,sizeof usage,nullptr)) return kal_ok; diff --git a/tests/a_unit_reference_names_its_boot_and_session.cpp b/tests/a_unit_reference_names_its_boot_and_session.cpp new file mode 100644 index 0000000..b5ea0f8 --- /dev/null +++ b/tests/a_unit_reference_names_its_boot_and_session.cpp @@ -0,0 +1,84 @@ +// What an observation of a unit answers (SPEC.md clause 7.18, version 0.26). +// +// A unit here is a named job in the session's namespace, and its reference +// (`W2') names the count of boots and the session beside the job's name. Until +// 0.23.0 it named neither: a reference of an earlier boot and one of another +// session both failed to open as a name that is not there, which a caller +// could not tell from a condition that passes. The cases alter a real +// reference one field at a time, which is how a reference from elsewhere reads +// to this program. +#include +#include +#include +#include +import mcpplibs.mtest; + +using namespace mcpplibs::mtest; + +namespace { + +std::vector fields(const std::string& r) { + std::vector out(1); + for (char c : r) { if (c == ';') out.emplace_back(); else out.back() += c; } + return out; +} +std::string joined(const std::vector& f) { + std::string out; + for (std::size_t i = 0; i < f.size(); ++i) { if (i) out += ';'; out += f[i]; } + return out; +} + +// What `open' answers, and the state an observation gives where it opens. +struct answer { int open = 0; kal_u32 state = KAL_JOB_UNKNOWN; }; +answer ask(const std::string& reference) { + answer a; kal_job job{}; + a.open = kal_process_job_open(reference.data(), reference.size(), &job); + if (a.open == kal_ok) { + kal_process_job_observe(job, reference.data(), reference.size(), &a.state); + kal_process_job_close(job); + } + return a; +} + +} // namespace + +UTest a_unit_reference_names_its_boot_and_session_test{"a_unit_reference_names_its_boot_and_session", [] { + expect(fatal((kal_process_props() & KAL_PROCESS_PROP_JOB_OBSERVE) != 0)) + << "this environment lets a reference be made, so observation is claimed"; + + // This program declares the unit and is its member for the whole test. + kal_job unit{}; char bytes[256]; kal_uintptr used = 0; + expect(fatal(kal_process_job_create(&unit, bytes, sizeof bytes, &used) == kal_ok)) << "a unit is declared"; + const std::string reference(bytes, used); + const auto f = fields(reference); + expect(fatal(f.size() == 6 && f[0] == "W2")) << "the reference is `W2;owner;birth;name;boot;session': " << reference; + + { + const auto a = ask(reference); + expect(a.open == kal_ok && a.state == KAL_JOB_OCCUPIED) + << "a unit with a running member is occupied (open " << a.open << ", state " << a.state << ")"; + } + // Another boot: every program of it has ended. A system that keeps no count + // of boots states none, and none is compared. + if (f[4] != "0") { + auto g = f; g[4] = std::to_string(std::stoull(f[4]) + 1); + const auto a = ask(joined(g)); + expect(a.open == kal_ok && a.state == KAL_JOB_EMPTY) + << "a reference of another boot is empty (open " << a.open << ", state " << a.state << ")"; + } + { // Another session: its names are not this session's. + auto g = f; g[5] = std::to_string(std::stoull(f[5]) + 1); + expect(ask(joined(g)).open == kal_err_not_supported) << "a reference of another session is not observable"; + } + { // A name the system no longer keeps: dropped with its last handle, + // whether or not a member remained. + auto g = f; char& last = g[3].back(); last = last == '0' ? '1' : '0'; + expect(ask(joined(g)).open == kal_err_not_supported) << "a unit whose name the system dropped is not observable"; + } + { // The earlier form names its unit by name alone and is answered by it. + auto g = f; g[0] = "W1"; g.resize(4); + const auto a = ask(joined(g)); + expect(a.open == kal_ok && a.state == KAL_JOB_OCCUPIED) << "a reference in the earlier form is answered by its name"; + } + kal_process_job_close(unit); +}}; From 46b6bf71c9c9342a7bf7a7d1c730c66f112d8b97 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Thu, 19 Nov 2026 12:14:24 +0900 Subject: [PATCH 2/2] A started program reads every argument and variable it was given The tables were fixed at 256 arguments, 512 variables and 64 KiB of text, and what did not fit was left out without a report. Both vectors are measured and held in allocations of their size (openkal 0.26, clause 7.6). --- README.md | 9 ++++--- src/env.cpp | 75 +++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 62 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index b644b6a..898950d 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,12 @@ is not there. A reference in the earlier form (`W1`) is answered by its name as before. `KAL_PROCESS_PROP_JOB_OBSERVE` is claimed where the session can be read and two handles compared. `tests/a_unit_reference_names_its_boot_and_session.cpp`. -**A start is bounded by the system alone** (clause 7.6). This implementation kept -no bound upon the number of arguments or variables; a command line beyond the -32,767 units the system takes is `kal_err_no_space`, as before. +**A start is bounded by the system alone** (clause 7.6). A started program read +its arguments and variables into fixed tables --- 256 arguments, 512 variables, +64 KiB of text --- and what did not fit was left out without a report: a program +given two thousand arguments counted 255. Both vectors are measured and held in +allocations of their size. A command line beyond the 32,767 units the system +takes is `kal_err_no_space`, as before. ## What 0.22.2 corrects diff --git a/src/env.cpp b/src/env.cpp index 465779c..177c19a 100644 --- a/src/env.cpp +++ b/src/env.cpp @@ -1,5 +1,6 @@ #include "win.h" #include +#include // the tables are sized by what the environment holds // The parameters a program receives at inception. // @@ -14,30 +15,33 @@ namespace { -constexpr int kMaxArgs = 256; -constexpr int kMaxVars = 512; -constexpr okw_uptr kText = 1u << 16; +// SIZED BY WHAT THE ENVIRONMENT HOLDS (0.23.0; openkal 0.26, clause 7.6). +// The tables were fixed --- 256 arguments, 512 variables, 64 KiB of text --- +// and what did not fit was left out without a word: a program started with +// two thousand arguments counted 255. A start is bounded by the environment +// alone, and that holds of what a program reads as much as of what its starter +// passes. Both vectors are measured, then held in one allocation each. +char* g_text = nullptr; +okw_uptr g_cap = 0; +okw_uptr g_used = 0; -char g_text[kText]; -okw_uptr g_used = 0; +const char** g_argv = nullptr; +okw_uptr* g_argv_len = nullptr; +int g_argc = 0; -const char* g_argv[kMaxArgs]; -okw_uptr g_argv_len[kMaxArgs]; -int g_argc = 0; - -const char* g_entry[kMaxVars]; // "name=value", as the environment states it -okw_uptr g_name_len[kMaxVars]; -const char* g_value[kMaxVars]; -okw_uptr g_value_len[kMaxVars]; -int g_varc = 0; +const char** g_entry = nullptr; // "name=value", as the environment states it +okw_uptr* g_name_len = nullptr; +const char** g_value = nullptr; +okw_uptr* g_value_len = nullptr; +int g_varc = 0; bool g_ready = false; // Arguments and named values are stored as they were given: neither is a name. const char* store(const wchar_t* w, int wlen, okw_uptr& out_len) { - if (g_used + 4 >= kText) { out_len = 0; return ""; } + if (g_used + 4 >= g_cap) { out_len = 0; return ""; } char* at = g_text + g_used; - const okw_uptr n = okw::narrow(w, static_cast(wlen), at, kText - g_used, false); + const okw_uptr n = okw::narrow(w, static_cast(wlen), at, g_cap - g_used, false); g_used += n + 1; out_len = n; return at; @@ -69,8 +73,42 @@ void prepare() { void fill() { int count = 0; wchar_t** parts = CommandLineToArgvW(GetCommandLineW(), &count); + wchar_t* block = GetEnvironmentStringsW(); + + // Measured first: the elements of each vector, and the units of both. A + // unit of this system's encoding is at most three bytes of the caller's. + okw_uptr units = 0; + int variables = 0; + if (!parts) count = 0; + for (int i = 0; i < count; ++i) units += static_cast(wide_length(parts[i])) + 1; + for (const wchar_t* p = block; p && *p; ) { + const int len = wide_length(p); + if (p[0] != L'=') { ++variables; units += static_cast(len) + 1; } + p += len + 1; + } + const okw_uptr slots = static_cast(count) + 1; + const okw_uptr vars = static_cast(variables) + 1; + g_cap = 3 * units + 8; + g_text = static_cast(kal_alloc(g_cap, 1)); + g_argv = static_cast(kal_alloc(slots * sizeof(char*), alignof(char*))); + g_argv_len = static_cast(kal_alloc(slots * sizeof(okw_uptr), alignof(okw_uptr))); + g_entry = static_cast(kal_alloc(vars * sizeof(char*), alignof(char*))); + g_name_len = static_cast(kal_alloc(vars * sizeof(okw_uptr), alignof(okw_uptr))); + g_value = static_cast(kal_alloc(vars * sizeof(char*), alignof(char*))); + g_value_len = static_cast(kal_alloc(vars * sizeof(okw_uptr), alignof(okw_uptr))); + // Without memory for them there is nothing to answer from: no argument but + // the empty first one, and no variable. + static const char* none[1] = { "" }; + static okw_uptr none_len[1] = { 0 }; + if (!g_text || !g_argv || !g_argv_len || !g_entry || !g_name_len || !g_value || !g_value_len) { + if (parts) LocalFree(parts); + if (block) FreeEnvironmentStringsW(block); + g_argv = none; g_argv_len = none_len; g_argc = 1; g_varc = 0; + return; + } + if (parts) { - for (int i = 0; i < count && g_argc < kMaxArgs - 1; ++i) { + for (int i = 0; i < count; ++i) { okw_uptr len = 0; // AS GIVEN, AND UNTIL 0.7.3 EVERY BACKSLASH CAME OUT AS A SLASH. // An argument is not a name: `C:\dir' and a pattern's `\d' are what @@ -88,9 +126,8 @@ void fill() { g_argv[0] = ""; g_argv_len[0] = 0; g_argc = 1; } - wchar_t* block = GetEnvironmentStringsW(); if (block) { - for (wchar_t* p = block; *p && g_varc < kMaxVars; ) { + for (wchar_t* p = block; *p && g_varc < variables; ) { const int len = wide_length(p); // A name beginning with a separator is this environment's own // bookkeeping and is not a variable a program set.