15.8 Environment and Runtime Information

► |  | 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:

system-type
system-language+ country
system-library-subpath
version
banner
current-command-line-arguments
current-thread-initial-stack-size
vector-set-performance-stats!

Racket
top contents ← prev up next →

### 15.8 Environment and Runtime Information🔗ℹ

> procedure (system-type [mode])
> → (or/c symbol? string? bytes? exact-positive-integer? vector? #f)
> | mode |  | : |  |
> (or/c 'os 'os* 'arch 'word 'so-find 'platform
> 'vm 'gc 'link 'machine 'target-machine
> 'so-suffix 'so-mode 'fs-change 'cross)
> |  | = |  | 'os

Returns information about the operating system, build mode, or machine for a running Racket. (Installation tools should use cross-system-type, instead, to support cross-installation.)

In 'os mode, the possible symbol results are:

- 'unix

- 'windows

- 'macosx

> > > Prior to the introduction of 'os* and 'arch modes, (system-library-subpath #f) could be used to obtain this information somewhat indirectly.

In 'os* mode, the result is similar to 'os mode, but refined to a specific operating system, such as 'linux or 'freebsd, instead of a generic 'unix classification.

In 'arch mode, the result is a symbol representing an architecture. Possible results include 'x86_64, 'i386, 'aarch64, 'arm (32-bit), and 'ppc (32-bit).

In 'word mode, the result is either 32 or 64 to indicate whether Racket is running as a 32-bit program or 64-bit program.

In 'so-find mode, the result is a symbol that identifies a convention for finding and managing platform-specific shared objects (i.e., dynamic libraries). Possible results include 'natipkg, meaning that native libraries are normally supplied through Racket packages, and 'system, meaning that they are normally managed through the operating system. Racket builds that are intended for use with other package managers can report symbols other than 'natipkg or 'system.

In 'platform mode, the result is a string that has the same information at the combination of 'os*, 'arch, and 'so-find to represent the platform. The 'so-find mode is omitted if it is the default for an 'os*: 'natipkg for Windows and Mac OS, 'system otherwise. A path form of the same string is returned by (system-library-subpath #f).

> > > See Racket Virtual Machine Implementations for more information about the 'vm and 'gc mode results.

In 'vm mode, the possible symbol results are (see also Implementations):

- 'racket

- 'chez-scheme

In 'gc mode, the possible symbol results are (see also Implementations):

- 'cgc — when (system-type 'vm) is 'racket

- '3m — when (system-type 'vm) is 'racket

- 'cs — when (system-type 'vm) is 'chez-scheme

In 'link mode, the possible symbol results are:

- 'static (Unix)

- 'shared (Unix)

- 'dll (Windows)

- 'framework (Mac OS)

Future ports of Racket may expand the list of 'os, 'os*, 'arch, 'vm, 'gc, and 'link results.

In 'machine mode, then the result is a string, which contains further details about the current machine in a platform-specific format.

In 'target-machine mode, the result is a symbol for the running Racket’s native bytecode format, or it is #f if there is no native format other than the machine-independent format. If the result is a symbol, then compile-target-machine? returns #t when applied to the symbol; see also current-compile-target-machine.

In 'so-suffix mode, then the result is a byte string that represents the file extension used for shared objects on the current platform. The byte string starts with a period, so it is suitable as a second argument to path-replace-suffix.

In 'so-mode mode, then the result is 'local if foreign libraries should be opened in “local” mode by default (as on most platforms) or 'global if foreign libraries should be opened in “global” mode.

In 'fs-change mode, the result is an immutable vector of four elements. Each element is either #f or a symbol, where a symbol indicates the presence of a property and #f indicates the absence of a property. The possible symbols, in order, are:

- 'supported — filesystem-change-evt can produce a filesystem change event to monitor filesystem changes; if this symbol is not first in the vector, all other vector elements are #f

- 'scalable — resources consumed by a filesystem change event are effectively limited only by available memory, as opposed to file-descriptor limits; this property is #f on Mac OS and BSD variants of Unix

- 'low-latency — creation and checking of a filesystem change event is practically instantaneous; this property is #f on Linux

- 'file-level — a filesystem change event can track changes at the level of a file, as opposed to the file’s directory; this property is #f on Windows

In 'cross mode, the result reports whether cross-platform build mode has been selected (through the -C or --cross argument to racket; see Command Line). The possible symbols are:

- 'infer — infer cross-platform mode based on whether (system-type) and (cross-system-type) report the same symbol

- 'force — use cross-platform mode, even if the current and target system types are the same, because the current and target executables can be different

Changed in version 6.8.0.2 of package base: Added 'vm mode.
Changed in version 6.9.0.1: Added 'cross mode.
Changed in version 7.1.0.6: Added 'target-machine mode.
Changed in version 7.9.0.6: Added 'os* and 'arch modes.
Changed in version 9.0.0.8: Added 'so-find and 'platform modes.

> procedure (system-language+country) → string?

Returns a string to identify the current user’s language and country.

On Unix and Mac OS, the string is five characters: two lowercase ASCII letters for the language, an underscore, and two uppercase ASCII letters for the country. On Windows, the string can be arbitrarily long, but the language and country are in English (all ASCII letters or spaces) separated by an underscore.

On Unix, the result is determined by checking the LC_ALL, LC_TYPE, and LANG environment variables, in that order (and the result is used if the environment variable’s value starts with two lowercase ASCII letters, an underscore, and two uppercase ASCII letters, followed by either nothing or a period). On Windows and Mac OS, the result is determined by system calls.

> procedure (system-library-subpath [mode]) → path?
> mode : (or/c 'cgc '3m 'cs #f) = (system-type 'gc)

Returns a relative directory path. This string can be used to build paths to system-specific files. For example, when Racket is running on Solaris on a Sparc architecture, the subpath starts "sparc-solaris", while the subpath for Windows on an i386 architecture starts "win32\\i386".

The optional mode argument specifies the relevant garbage-collection variant, which one of the possible results of (system-type 'gc): 'cgc, '3m, or 'cs. It can also be #f, in which case the result is independent of the garbage-collection variant, and its string form is the same as the result of (system-type 'platform).

Installation tools should use cross-system-library-subpath, instead, to support cross-installation.

Changed in version 7.0 of package base: Added 'cs mode.

> procedure (version) → (and/c string? immutable?)

Returns an immutable string indicating the currently executing version of Racket.

> procedure (banner) → (and/c string? immutable?)

Returns an immutable string for Racket’s start-up banner text (or the banner text for an embedding program, such as GRacket). The banner string ends with a newline.

> parameter (current-command-line-arguments)
> → (vectorof (and/c string? immutable?))
> (current-command-line-arguments argv) → void?
> argv : (vectorof string?)

A parameter that is initialized with command-line arguments when Racket starts (not including any command-line arguments that were treated as flags for the system).

On Unix and Mac OS, command-line arguments are provided to the Racket process as byte strings. The arguments are converted to strings using bytes->string/locale and #\uFFFD as the encoding-error character.

> parameter (current-thread-initial-stack-size) → exact-positive-integer?
> (current-thread-initial-stack-size size) → void?
> size : exact-positive-integer?

A parameter that provides a hint about how much space to reserve for a newly created thread’s local variables. The actual space used by a computation is affected by JIT compilation, but it is otherwise platform-independent.

> procedure (vector-set-performance-stats! results [thd]) → void?
> | results |  | : |  |
> (and/c vector?
> (not/c immutable?))
> thd : (or/c thread? #f) = #f

Sets elements in results to report current performance statistics. If thd is not #f, a particular set of thread-specific statistics are reported, otherwise a different set of global (within the current place) statistics are reported.

For global statistics, up to 12 elements are set in the vector, starting from the beginning. If results has n elements where n < 12, then the n elements are set to the first n performance-statistics values. The reported statistics values are as follows, in the order that they are set within results:

- 0: The same value as returned by current-process-milliseconds.

- 1: The same value as returned by current-milliseconds.

- 2: The same value as returned by current-gc-milliseconds.

- 3: The number of garbage collections performed since start-up within the current place.

- 4: The number of thread context switches performed since start-up.

- 5: The number of internal stack overflows handled since start-up (BC only; 0 for CS).

- 6: The number of threads currently scheduled for execution (i.e., threads that are running, not suspended, and not unscheduled due to a synchronization).

- 7: The number of syntax objects read from compiled code since start-up (BC only; 0 for CS).

- 8: The number of hash-table searches performed (BC only; 0 for CS). When this counter reaches the maximum value of a fixnum, it overflows to the most negative fixnum.

- 9: The number of additional hash slots searched to complete hash searches using double hashing (BC only; 0 for CS). When this counter reaches the maximum value of a fixnum, it overflows to the most negative fixnum.

- 10: The number of bytes allocated for machine code that is not reported by current-memory-use (BC only; 0 for CS).

- 11: The peak number of allocated bytes just before a garbage collection.

For thread-specific statistics, up to 4 elements are set in the vector:

- 0: #t if the thread is running, #f otherwise (same result as thread-running?).

- 1: #t if the thread has terminated, #f otherwise (same result as thread-dead?).

- 2: #t if the thread is currently blocked on a synchronizable event (or sleeping for some number of milliseconds), #f otherwise.

- 3: The number of bytes currently in use for the thread’s continuation (BC only; 0 for CS).

Changed in version 6.1.1.8 of package base: Added vector position 11 for global statistics.

top contents ← prev up next →