putenv

Putenv is a standard library function used to modify the environment of the running process. It adds or changes an environment variable by taking a string of the form NAME=VALUE and placing a pointer to that string into the process's environment table. The exact mechanism is platform dependent, but on most Unix-like systems the environment is represented by an array of strings that can be updated by putenv.

Prototype and usage: in C, putenv is declared in stdlib.h as int putenv(char *string). The string passed to putenv must have the form NAME=VALUE. The implementation may or may not copy this string; often it stores the pointer directly in the environment array and relies on the string existing for the lifetime of the program.

Memory considerations and return value: because the environment entry may reference the provided string, the caller should allocate the string in a persistent region and not free or modify it while it is in use. If the string becomes invalid, the environment contents may become undefined. The function returns 0 on success and a nonzero value on error, with errno set accordingly on many platforms.

Portability and alternatives: POSIX defines setenv and unsetenv as preferred alternatives, because they clearly copy the value into the environment and do not require a persistent caller-supplied string. Setenv takes separate NAME and VALUE arguments and returns 0 on success. Windows provides _putenv and _putenv_s with similar purpose, but semantics can differ from POSIX.

See also: setenv, unsetenv, environ.