[FEATURE] Mutate the process environment on the shared heap #12

Open
opened 2026-10-26 21:41:18 +01:00 by erikinkinen · 1 comment
Owner

Problem and motivation

Compilers and build tools need to update the process environment and pass selected values to child programs. LibCstd needs the conventional mutation calls alongside its existing startup environment and getenv.

Proposed behavior and scope

Add setenv, unsetenv, putenv and clearenv to the process-root startup provider, using its existing shared process heap. Read the current environ table, including a synchronized caller replacement or a NULL empty environment. setenv copies its input; putenv retains the caller's actual string so later synchronized edits remain visible.

Support checked table growth without a private entry or string-length limit. Keep allocation failure atomic and allow environment access from exit handlers while process backing remains live. Child environment transfer remains explicit.

Authority, security and reliability

Use the retained heap and environment cell without service discovery or new native capabilities. Names and values confer no filesystem or service rights. Never free caller-owned putenv strings, replacement tables or startup backing. Reclaim runtime-owned storage only when the current table and entries no longer refer to it, including interior aliases.

Preserve errno on success and report invalid names or allocation failure without losing the previous environment. Document returned-pointer lifetime, direct mutation and concurrency requirements.

Acceptance criteria

Checked items cover the implementation and authored probes. Execution and warning-free acceptance remain in the final item.

  • Implement the four mutation calls and current-table getenv with documented Rust/C/C++ interfaces and native aliases.
  • Preserve overwrite behavior, exact bytes and pointers, direct environ replacement and caller-owned putenv edits.
  • Keep invalid-name and heap-exhaustion failures atomic, with correct errno and recovery after removal.
  • Cover aliases, repeated replacement, duplicates, empty state, concurrent calls and exit-handler access without freeing foreign storage.
  • Wire independent native C probes and update the component contracts and technical manual.
  • Complete warning-free component checks and the actual native workload.

Alternatives and tradeoffs

Reuse the process heap and lifetime owner. A separate environment arena would add capacity policy and duplicate ownership. Raw C access still requires caller synchronization because a library lock cannot protect pointers used after a call returns.

Tracking and rollout

Extend ordinary C startup over the shared heap, under the C runtime. Overall work is tracked in Phase 6.

## Problem and motivation Compilers and build tools need to update the process environment and pass selected values to child programs. LibCstd needs the conventional mutation calls alongside its existing startup environment and getenv. ## Proposed behavior and scope Add setenv, unsetenv, putenv and clearenv to the process-root startup provider, using its existing shared process heap. Read the current environ table, including a synchronized caller replacement or a NULL empty environment. setenv copies its input; putenv retains the caller's actual string so later synchronized edits remain visible. Support checked table growth without a private entry or string-length limit. Keep allocation failure atomic and allow environment access from exit handlers while process backing remains live. Child environment transfer remains explicit. ## Authority, security and reliability Use the retained heap and environment cell without service discovery or new native capabilities. Names and values confer no filesystem or service rights. Never free caller-owned putenv strings, replacement tables or startup backing. Reclaim runtime-owned storage only when the current table and entries no longer refer to it, including interior aliases. Preserve errno on success and report invalid names or allocation failure without losing the previous environment. Document returned-pointer lifetime, direct mutation and concurrency requirements. ## Acceptance criteria Checked items cover the implementation and authored probes. Execution and warning-free acceptance remain in the final item. - [x] Implement the four mutation calls and current-table getenv with documented Rust/C/C++ interfaces and native aliases. - [x] Preserve overwrite behavior, exact bytes and pointers, direct environ replacement and caller-owned putenv edits. - [x] Keep invalid-name and heap-exhaustion failures atomic, with correct errno and recovery after removal. - [x] Cover aliases, repeated replacement, duplicates, empty state, concurrent calls and exit-handler access without freeing foreign storage. - [x] Wire independent native C probes and update the component contracts and technical manual. - [ ] Complete warning-free component checks and the actual native workload. ## Alternatives and tradeoffs Reuse the process heap and lifetime owner. A separate environment arena would add capacity policy and duplicate ownership. Raw C access still requires caller synchronization because a library lock cannot protect pointers used after a call returns. ## Tracking and rollout Extend [ordinary C startup](https://git.erikinkinen.fi/erix/lib-cstd/issues/9) over [the shared heap](https://git.erikinkinen.fi/erix/lib-cstd/issues/8), under [the C runtime](https://git.erikinkinen.fi/erix/lib-cstd/issues/1). Overall work is tracked in [Phase 6](https://git.erikinkinen.fi/erix/integration/issues/65).
Author
Owner

The environment APIs are implemented in 37013e5. They use the shared process heap, follow the current environ table and retain runtime-owned storage while borrowed strings or table aliases still reference it. The native C probes, manual and Integration oracle cover the same contract. Native execution remains open.

The environment APIs are implemented in [37013e5](https://git.erikinkinen.fi/erix/lib-cstd/commit/37013e58b5705adcb09813df71b193cfed9b2007). They use the shared process heap, follow the current `environ` table and retain runtime-owned storage while borrowed strings or table aliases still reference it. The [native C probes](https://git.erikinkinen.fi/erix/posixd/commit/d3f06acdde912e4baa273748d8864756eaaab90c), [manual](https://git.erikinkinen.fi/erix/docs/commit/a315be7513829777c085586ef3f27b1641fec06b) and [Integration oracle](https://git.erikinkinen.fi/erix/integration/commit/c0d0feb8befa9932555e01849a925a9aee3632a7) cover the same contract. Native execution remains open.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:34:40 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/lib-cstd#12
No description provided.