18.2.244. PMIx_Setenv

PMIx_Setenv — Set an environment variable in a caller-provided environment array

18.2.244.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Setenv(const char *name,
                          const char *value,
                          bool overwrite,
                          char ***env);

18.2.244.1.1. Python Syntax

No Python equivalent

18.2.244.2. INPUT PARAMETERS

  • name: Name of the environment variable to set.

  • value: Value to assign to the variable. If NULL, the variable is either removed (when env refers to the process environ) or set to an empty value.

  • overwrite: If true, replace any existing entry for name; if false, leave an existing entry unchanged.

18.2.244.3. INPUT/OUTPUT PARAMETERS

  • env: Address of an argv-style, NULL-terminated array of "name=value" strings to be updated. Must not be NULL. The pointed-to array may be grown (reallocated) to accommodate a new entry.

18.2.244.4. DESCRIPTION

Set an environment variable within a caller-supplied environment array, using argv-style "name=value" string conventions.

The behavior depends on what env references:

  • If *env is the process environ, the operation is delegated to the C library: a NULL value performs an unsetenv(name), otherwise setenv(name, value, overwrite) is called.

  • Otherwise the routine operates on the caller’s array. A new "name=value" string (or "name=" when value is NULL) is formatted. If *env is NULL or contains no entry for name, the new string is appended, growing the array. If an entry for name already exists, it is replaced when overwrite is true and left untouched (returning PMIX_ERR_EXISTS) when overwrite is false.

Memory for the array entries is managed by the library; strings that are replaced are freed and the array is reallocated as needed.

18.2.244.5. RETURN VALUE

Returns one of the following pmix_status_t values:

  • PMIX_SUCCESS: The variable was set (or unset), or already existed and overwrite was false for the environ fast path.

  • PMIX_ERR_BAD_PARAM: The env argument was NULL.

  • PMIX_ERR_EXISTS: An entry for name already existed in a caller-provided array and overwrite was false.

  • PMIX_ERR_OUT_OF_RESOURCE: Memory for the new entry could not be allocated.

18.2.244.6. NOTES

PMIx_Setenv is an OpenPMIx convenience routine. When *env points at the global environ, the update follows C-library setenv/unsetenv semantics; for any other array the entry is stored using PMIx argv-style management. The array remains NULL-terminated after the call.