On this page:
environment-variables?
current-environment-variables
bytes-environment-variable-name?
make-environment-variables
environment-variables-ref
environment-variables-set!
environment-variables-names
environment-variables-copy
getenv
putenv
string-environment-variable-name?

15.7 Environment Variables

An environment variable set encapsulates a partial mapping from byte strings to bytes 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, and 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.

procedure

(environment-variables? v)  boolean?

  v : any/c
Returns #t if v is an environment variable set, #f otherwise.

A parameter that determines the environment variable set that is propagated to a subprocess and that is used as the default set for getenv and putenv.

procedure

(bytes-environment-variable-name? v)  boolean?

  v : any/c
Returns #t if v is a byte string and if it is valid for an environment variable name. An environment variable name must contain no bytes with the value 0 or 61, where 61 is (char->integer #\=). On Windows, an environment variable name also must have a non-zero length.

procedure

(make-environment-variables name val ... ...)

  environment-variables?
  name : bytes-environment-variable-name?
  val : bytes-no-nuls?
Creates a fresh environment variable set that is initialized with the given name to val mappings.

Returns the mapping for name in env, returning #f if name has no mapping.

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.

procedure

(environment-variables-set! env    
  name    
  maybe-bstr    
  [fail])  any
  env : environment-variables?
  name : bytes-environment-variable-name?
  maybe-bstr : (or/c bytes-no-nuls? #f)
  fail : (-> any) = 
(lambda ()
  (raise (make-exn:fail ....)))
Changes the mapping for name in env to maybe-bstr. If maybe-bstr is #f and env is the initial environment variable set of the Racket process, then the operating system environment-variable mapping for name is removed.

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.

Returns a list of byte strings that corresponds to names mapped by env.

Returns an environment variable set that is initialized with the same mappings as env.

procedure

(getenv name)  (or/c string-no-nuls? #f)

  name : string-environment-variable-name?

procedure

(putenv name value)  boolean?

  name : string-environment-variable-name?
  value : string-no-nuls?
Convenience wrappers for environment-variables-ref and environment-variables-set! that convert between strings and byte strings using the current locale’s default encoding (using #\? as the replacement character for encoding errors) and always using the current environment variable set from current-environment-variables. The putenv function returns #t for success and #f for failure.

procedure

(string-environment-variable-name? v)  boolean?

  v : any/c
Returns #t if v is a string and if its encoding using the current locale’s encoding is valid for an environment variable name according to bytes-environment-variable-name?.