15.7 Environment Variables

An environment variable set encapsulates a partial mapping from byte strings to byte strings. A Racket process’s initial environment variable set is connected to the operating system’s environment variables: accesses or changes to the set read or change operating-system environment variables for the Racket process.

Since Windows environment variables are case-insensitive, environment variable set’s key byte strings on Windows are case-folded. More precisely, key byte strings are coerced to a UTF-8 encoding of characters that are converted to lowercase via string-locale-downcase.

The current environment variable set, which is determined by the current-environment-variables parameter, is propagated to a subprocess when the subprocess is created.

Normally, name should be a byte-string encoding of a string using the default encoding of the current locale. On Windows, name is coerced to a UTF-8 encoding and case-normalized.

Normally, name and maybe-bstr should be a byte-string encoding of a string using the default encoding of the current locale. On Windows, name is coerced to a UTF-8 encoding and case-normalized, and maybe-bstr is coerced to a UTF-8 encoding if env is the initial environment variable set of the Racket process.

On success, the result of environment-variables-set! is #<void>. If env is the initial environment variable set of the Racket process, then attempting to adjust the operating system environment-variable mapping might fail for some reason, in which case fail is called in tail position with respect to the environment-variables-set!. The default fail raises an exception.