GETENV Function (Gnumeric)
Read a named process-environment value with Gnumeric GETENV, using harmless synthetic variables and checking missing-variable errors.
Verification status: See the evidence and test scope described in this guide. How formula examples are checked
GETENV reads a named variable from the environment of the running Gnumeric process and returns its value as text. It can help identify a deliberately configured calculation environment, such as a test-run label. It does not read worksheet names, change the operating system’s environment, or retrieve arbitrary configuration settings from other applications.
Syntax and scope
GETENV(name)
name is a quoted environment-variable name or a cell containing that name. Names are case-sensitive according to the function’s documented contract. If the variable is absent, GETENV returns #N/A. The 1.12.57 implementation also returns #N/A when the existing value is not valid UTF-8 text.
The relevant environment is the one inherited by Gnumeric when its process starts. A value set in a different terminal after the application has launched is not automatically part of that already-running process. This distinction is particularly important when comparing a desktop-launched workbook with a command-line conversion.
Reproducible synthetic example
Use a harmless variable created specifically for the test. In a POSIX shell, an invocation such as the following sets the value only for the launched Gnumeric process:
ST_GUIDE_EXAMPLE=synthetic-value gnumeric
In that application instance, enter:
| Formula | Expected result |
|---|---|
=GETENV("ST_GUIDE_EXAMPLE") |
synthetic-value |
=GETENV("st_guide_example") |
#N/A, if this separate lowercase variable is absent |
=GETENV("ST_GUIDE_MISSING_20261017") |
#N/A, if this test name is absent |
The exact three cases were checked by the 1.12.57 calculation engine with only the synthetic uppercase variable supplied to its child process. No existing personal environment values were used in the examples. The shell launch command itself is a setup illustration, not a claimed GUI test.
Advanced use: label controlled calculation runs
A batch-conversion workflow can supply a non-sensitive run label and display it in a workbook’s diagnostics. This helps reviewers distinguish outputs produced under different controlled settings. Keep the variable’s meaning documented and set it explicitly for each process; a label inherited accidentally from a parent shell is weak provenance.
GETENV is not a secure configuration channel. A workbook that displays a value may preserve that value in a cached result, export, printed report, or shared copy. Use synthetic labels and ordinary non-sensitive settings. Do not query passwords, tokens, or other secrets merely to demonstrate that environment access works.
For a portable workbook, consider storing ordinary configuration in a clearly labeled input sheet instead. A workbook sent to another person does not carry your process environment with it, so recalculation may legitimately produce a different result or #N/A.
Errors and troubleshooting
#N/Ausually indicates an absent variable, but the source also rejects invalid UTF-8 values; do not infer absence as the only possible cause.- Check exact capitalization and how the Gnumeric process was launched.
- Restart the appropriate process with the intended synthetic setting when testing inheritance. Editing a cell does not create an operating-system variable.
- If a copied workbook shows an old label, distinguish a cached displayed value from a newly recalculated result.
- The function returns text even when the variable looks numeric. Parse and validate numerical configuration deliberately rather than relying on implicit conversion.
Version and verification
Official release notes record GETENV as added in Gnumeric 1.0.1. This guide’s behavior is pinned to the 1.12.57 callback and the three synthetic native cases run under C.UTF-8 on 17 October 2026. Invalid UTF-8 values and GUI launching were not tested. No retirement or last-working-release claim is made.