15.7 Environment Variables

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 15 | Operating System

15.1 | Paths
15.2 | Filesystem
15.3 | Networking
15.4 | Processes
15.5 | Logging
15.6 | Time
15.7 | Environment Variables
15.8 | Environment and Runtime Information
15.9 | Command-Line Parsing
15.10 | Additional Operating System Functions

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?

Racket
top contents ← prev up next →

### 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.

> procedure (environment-variables? v) → boolean?
> v : any/c

Returns #t if v is an environment variable set, #f otherwise.

> parameter (current-environment-variables) → environment-variables?
> (current-environment-variables env) → void?
> env : environment-variables?

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.

> procedure (environment-variables-ref env name)
> → (or/c #f (and/c bytes-no-nuls? immutable?))
> env : environment-variables?
> name : bytes-environment-variable-name?

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.

> procedure (environment-variables-names env)
> → (listof (and/c bytes-environment-variable-name? immutable?))
> env : environment-variables?

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

> procedure (environment-variables-copy env) → environment-variables?
> env : environment-variables?

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?.
top contents ← prev up next →