RunMat
GitHub

View all functions

CategoryIo: Repl Fs

What does the getenv function do in MATLAB / RunMat?

getenv reads environment variables that are visible to the current process. When you call getenv("NAME"), the builtin returns the value of the environment variable NAME, matching MATLAB behaviour. Supplying no input arguments returns a struct where each field corresponds to an environment variable.

How does the getenv function behave in MATLAB / RunMat?

  • Accepts character vectors ('PATH') or string scalars ("PATH"). Character vector inputs return character vectors; string inputs return string scalars.
  • Vectorised calls are supported: pass a string array to receive a string array of values, or a cell array of character vectors to receive a cell array of character vectors.
  • When the requested variable is not defined, getenv returns an empty character vector or an empty string scalar (depending on the input type). This matches MATLAB’s “variable not found” semantics.
  • Calling getenv with no arguments returns a scalar struct. Field names are the environment variable names; field values are character vectors containing each variable’s value.
  • On Windows, environment variable lookups are case-insensitive, mirroring the operating system. On Unix-like systems, lookups are case-sensitive.
  • Trailing spaces in character matrix inputs are ignored so that padded rows created with MATLAB’s string manipulation functions remain compatible.
  • The builtin rejects non-text inputs (numeric arrays, logicals, GPU tensors, etc.) with a clear MATLAB-style diagnostic.

getenv Function GPU Execution Behaviour

getenv always runs on the CPU. If the argument originates from the GPU—for example, a string scalar produced by an accelerated builtin—RunMat gathers it to host memory before reading the environment. No GPU kernels are launched, and acceleration providers do not need to implement hooks for this builtin.

GPU residency in RunMat (Do I need gpuArray?)

No. getenv has no GPU implementation and simply queries the host environment. Passing GPU-resident values is supported (RunMat gathers them automatically), but there is no benefit to calling gpuArray yourself.

Examples of using the getenv function in MATLAB / RunMat

Read A Single Environment Variable

homeFolder = getenv("HOME");
disp(homeFolder);

Expected output (macOS/Linux):

homeFolder =
    "/Users/alex"

Expected output (Windows):

homeFolder =
    "C:\Users\alex"

Handle Missing Environment Variables

token = getenv("RUNMAT_TOKEN");
if token == ""
    warning("Token not configured.");
end

Expected output:

Warning: Token not configured.

Fetch Multiple Variables With A String Array

vars = getenv(["PATH", "SHELL"]);
disp(vars);

Expected output:

vars = 1x2 string
    "/usr/local/bin:/usr/bin:..."    "/bin/zsh"

Use A Cell Array Of Character Vectors

cells = getenv({'HOME', 'PATH'});
disp(cells{1});

Expected output:

cells =
  1x2 cell array
    {'/Users/alex'}    {'/usr/local/bin:/usr/bin:...'}

Inspect All Environment Variables

env = getenv();
disp(env.USER);

Expected output:

env =
  struct with fields:
    HOME: '/Users/alex'
    PATH: '/usr/local/bin:/usr/bin:...'
    USER: 'alex'

Cache The Environment For Repeated Access

env = getenv();
resultsFolder = fullfile(env.HOME, "results");

Expected output:

resultsFolder =
    "/Users/alex/results"

FAQ

What does getenv return when the variable is missing?

An empty character vector ('') for character inputs, or an empty string scalar ("") for string inputs. You can test for a missing variable with isempty(value) or value == "".

Does getenv support vectorised inputs?

Yes. Pass a string array or a cell array of character vectors to retrieve multiple values in one call. The output mirrors the input container type.

Are environment variable lookups case-sensitive?

RunMat follows the operating system. Lookups are case-insensitive on Windows and case-sensitive on Unix-like systems, matching MATLAB.

Does getenv modify the environment?

No. It is a read-only operation. Use the forthcoming setenv builtin to modify the environment once it is available.

Can I call getenv from GPU-accelerated code?

Yes. Inputs originating on the GPU are gathered automatically. The builtin still executes on the CPU, and the output lives on the host.

How do I access all environment variables at once?

Call getenv() with no arguments. The result is a struct whose fields contain character vectors for each environment variable.

What happens if an environment variable name is not a valid struct field?

RunMat preserves the exact name as a struct field. Access it via dynamic field references when the name contains characters that cannot be used in dot notation.

Are trailing spaces in character inputs significant?

No. Trailing spaces introduced by padding character matrices are stripped before the lookup so that MATLAB-style character arrays work as expected.

Does getenv include inherited environment variables?

Yes. The builtin reports every variable visible to the RunMat process, including inherited values.

See Also

tempdir, tempname, pwd, path

Source & Feedback