RunMat
GitHub

View all functions

CategoryIo: Repl Fs

setenv — Set or clear environment variables with MATLAB-compatible status outputs.

setenv updates the process environment. Provide a variable name and value to create or modify an entry, or pass an empty value to remove the variable. The builtin mirrors MATLAB by returning a status code and optional diagnostic message instead of throwing for platform-defined failures.

How does the setenv function behave in MATLAB / RunMat?

  • status = setenv(name, value) returns 0 when the update succeeds and 1 when the operating system rejects the request. The status output is a double scalar, matching MATLAB.
  • [status, message] = setenv(name, value) returns the status plus a character vector describing failures. On success, message is an empty 1×0 character array.
  • Set value to an empty string ("") or empty character vector ('') to remove the variable from the current process environment.
  • Names must be string scalars or character vectors containing only valid environment variable characters. MATLAB raises an error when name is not text; RunMat mirrors this check.
  • Character vector inputs trim trailing padding spaces (common with MATLAB character matrices). To retain trailing spaces, pass a string scalar instead.
  • Environment updates apply to the RunMat process and any child processes it spawns. They do not modify the parent shell.

GPU behavior

setenv always runs on the CPU. If a caller stores the arguments on the GPU—for instance via an accelerated string builtin—RunMat gathers them to host memory automatically before mutating the environment. Acceleration providers do not implement hooks for this builtin.

GPU residency

No. setenv is a host-side operation. GPU residency offers no benefit, and RunMat gathers GPU-backed values automatically if they appear as inputs.

Examples of using setenv in MATLAB / RunMat

Set a new environment variable for the current session

status = setenv("RUNMAT_MODE", "development")

Expected output:

status =
     0

Update an existing environment variable

status = setenv("PATH", string(getenv("PATH")) + ":~/runmat/bin")

Expected output:

status =
     0

Remove an environment variable with an empty value

[status, message] = setenv("OLD_SETTING", "")

Expected output:

status =
     0

message =

Capture diagnostic messages when a name is invalid

[status, message] = setenv("INVALID=NAME", "value")

Expected output:

status =
     1

message =
Environment variable names must not contain '='.

Use character vectors from legacy code

status = setenv('RUNMAT_LEGACY', 'enabled')

Expected output:

status =
     0

Combine setenv with child process launches

setenv("RUNMAT_DATASET", "demo");
status = system("runmat-cli process-data")

Expected output:

status =
     0

FAQ

What status codes does setenv return?

0 means success; 1 means the operating system rejected the request (for example, due to an invalid name or an oversized value on Windows).

Does setenv throw errors?

Only when the inputs are the wrong type (non-text). Platform failures are reported through the status and message outputs so scripts can handle them programmatically.

How do I remove a variable?

Pass an empty string or empty character vector as the value.

Are names case-sensitive?

RunMat defers to the operating system: case-sensitive on Unix-like systems and case-insensitive on Windows.

Can I include trailing spaces in the value?

Use string scalars to preserve trailing spaces. Character vector inputs trim trailing padding spaces by design.

Does setenv affect the parent shell?

No. Changes are limited to the current RunMat process and any child processes launched afterwards.

What characters are disallowed in names?

setenv rejects names containing = or null characters. Additional platform-specific restrictions are enforced by the operating system and reported through the status/message outputs.

Can I call setenv from GPU-enabled code?

Yes. Arguments are gathered from the GPU before updating the environment; the operation itself always runs on the CPU.

How can I check whether the update succeeded?

Inspect the returned status. When it is 1, read the accompanying message to determine why the operation failed.

Will the variable persist after I exit RunMat?

No. Environment modifications are scoped to the current process.

See also

getenv, mkdir, pwd

Source & Feedback