The operating-system Module¶

The operating-system module is part of the System library. It provides an interface to some features of the host machine’s operating system.

Manipulating environment information¶

The operating-system module contains a number of interfaces for examining and specifying information about the operating system environment of the host machine. As well as providing constants that you can use in your code, you can examine and set the value of any environment variable in the system.

The following constants contain machine-specific information:

$architecture-little-endian?
$machine-architecture
$os-name
$os-variant
$os-version
$platform-name

These constants contain information about the hardware and software resident on the host machine. The constants let you programmatically check the current system conditions before executing a piece of code.

The following function also returns information about the machine:

machine-concurrent-thread-count

The following two functions let you manipulate the values of any environment variables in the system.

environment-variable
environment-variable-setter

The following functions access information about the user logged on to the current machine, where available.

login-name
login-group
owner-name
owner-organization

The following functions are defined in the common-dylan library and re-exported from the operating-system module:

Working with shared libraries¶

load-library

The operating-system module¶

This section contains a reference entry for each item exported from the System library’s operating-system module.

$architecture-little-endian? Constant¶

Constant specifying whether the processor architecture is little-endian.

Type:

Discussion:

This constant is a boolean value that is true if the processor architecture is little-endian and false if it is big-endian. (A processor is little-endian if the rightmost bit in a word is the least-significant bit.) For processors implementing the Intel x86 architecture this value is #t.

See also:

$machine-architecture
$os-name
$os-variant
$os-version
$platform-name

current-process-id Function¶

Returns the integer value for the current process ID.

Signature:

current-process-id => pid

Values:

pid – An instance of <integer>.

Discussion:

Returns the integer value of the current process ID.

See also:

environment-variable Function¶

Returns the value of a specified environment variable.

Signature:

environment-variable name => value

Parameters:

name – An instance of <byte-string>.

Values:

value – An instance of <byte-string>, or #f.

Discussion:

Returns the value of the environment variable specified by name, or #f if there is no such environment variable.

See also:

environment-variable-setter

environment-variable-setter Function¶

Sets the value of an environment variable.

Signature:

environment-variable-setter new-value name => new-value

Parameters:

new-value – An instance of <byte-string>, or #f.
name – An instance of <byte-string>.

Values:

new-value – An instance of <byte-string>, or #f.

Discussion:

Changes the value of the environment variable specified by name to new-value. If new-value is #f, the environment variable is undefined. If the environment variable does not already exist, environment-variable-setter creates it.

Note

Windows 95 places restrictions on the number of environment variables allowed, based on the total length of the names and values of the existing environment variables. The function environment-variable-setter only creates a new environment variable if it is possible within these restrictions. See the relevant Windows 95 documentation for more details.

See also:

environment-variable

load-library Function¶

Loads a shared library into the current process.

Signature:

load-library name => module

Parameters:

name – An instance of <string>.

Values:

module – An instance of <machine-word>.

Discussion:

Loads the library specified by name into the current process. The library must be a shared library.

If the library is a library written in Dylan, then when it loaded, constructor functions will run which set up the various methods and other Dylan objects within the shared library. Top level code within the library will be executed.

Load-time failures, for example due to missing files or unsatisfied symbol dependencies, will cause an <error> condition to be signaled.

Note

Dynamic loading of Dylan code is currently only supported on non-Windows platforms using the LLVM back-end, and on Windows using the HARP back-end.

login-name Function¶

Returns as an instance of <string> the name of the user logged on to the current machine, or #f if unavailable.

Signature:

Values:

name-or-false – An instance of false-or(<string>).

Discussion:

Returns as an instance of <string> the name of the user logged on to the current machine, or #f if unavailable.

See also:

login-group

login-group Function¶

Signature:

Values:

group-or-false – An instance of false-or(<string>).

Discussion:

Returns as an instance of <string> the group (for example NT domain, or Windows Workgroup) of which the user logged on to the current machine is a member, or #f if the group is unavailable.

See also:

login-name

$machine-architecture Constant¶

Constant specifying the type of hardware installed in the host machine.

Type:

<symbol>

Value:

One of #"aarch64", #"arm", #"riscv64" #"x86", #"x86_64"

Discussion:

This constant represents the execution platform’s instruction set architecture.

Note that this not always the same as the architecture of the hardware installed in the host machine. For example, when running x86_64 code on Apple Silicon the value is #"x86_64, not #"aarch64".

See also:

$architecture-little-endian?
$os-name
$os-variant
$os-version
$platform-name

$machine-name Constant¶: Deprecated since version 2024.2: Use $machine-architecture instead.

This constant will be removed in a future release.

$os-name Constant¶

Constant specifying the operating system running on the host machine.

Type:

<symbol>

Value:

One of #"darwin", #"freebsd", #"linux", #"netbsd", #"win32"

Discussion:

This constant is a symbol that represents the operating system running on the host machine.

See also:

$architecture-little-endian?
$machine-architecture
$os-variant
$os-version
$platform-name

$os-variant Constant¶

Constant specifying which variant of an operating system the current machine is running, where relevant.

Type:

<symbol>

Discussion:

This constant is a symbol value distinguishing between variants of the operating system identified by $os-name, where relevant; otherwise it has the same value as $os-name. On Windows, the possible values are #"win3.1", #"win95", #"win98", and #"winnt".

See also:

$architecture-little-endian?
$machine-architecture
$os-name
$os-version
$platform-name

$os-version Constant¶

Constant specifying which version of an operating system the current machine is running.

Type:

<string>

Discussion:

The constant $os-version is a string value that identifies the version of the operating system. For Windows NT, a typical value would be “4.0.1381 Service Pack 3”. For Windows 95, a typical value would be “4.0.1212 B”.

See also:

$architecture-little-endian?
$machine-architecture
$os-name
$os-variant
$platform-name

owner-name Function¶

Returns the name of the user who owns the current machine, if available.

Signature:

owner-name () => name-or-false

Values:

name-or-false – An instance of false-or(<string>).

Discussion:

Returns as an instance of <string> the name of the user who owns the current machine (that is, the name entered when the machine was registered), or #f if the name is unavailable.

owner-organization Function¶

Returns the organization to which the user who owns the current machine belongs, if available.

Signature:

owner-organization () => organization-or-false

Values:

organization-or-false – An instance of false-or(<string>).

Discussion:

Returns as an instance of <string> the organization to which the user who owns the current machine belongs, or #f if the name is unavailable.

parent-process-id Function¶

Returns the integer value for the parent process ID.

Signature:

parent-process-id => pid

Values:

pid – An instance of <integer>.

Discussion:

Returns the integer value of the parent process ID.

Note

This is not yet implemented on Windows.

See also:

$platform-name Constant¶

Constant specifying the operating system running on and the type of hardware installed in the host machine.

Type:

<symbol>

Value:

#"x86-win32", #"x86_64-darwin", etc.

Discussion:

Represents both the architecture and the operating system running on the host machine. It is a symbol created from the concatenation of $machine-architecture, "-", and $os-name. See those constants to determine the full list of possible values.

Example:

#"x86-win32", #"x86_64-linux"

See also:

$machine-architecture
$os-name

machine-concurrent-thread-count Function¶

Return the number of concurrent execution threads available.

Signature:

machine-concurrent-thread-count => count

Values:

count – An instance of <integer>.

Discussion:

Returns the number of execution threads currently available. This normally corresponds to the number of logical processor cores currently online, and may vary over the lifetime of the program.

run-application Function¶

Launches an application in a new process, using the specified name and arguments.

Signature:

run-application command #key minimize? activate? under-shell? inherit-console? outputter asynchronous? environment working-directory input if-input-does-not-exist output if-output-exists error if-error-exists hide? => status signal process #rest streams

Parameters:

command –
An instance of <sequence>. Either a string containing the entire command or a sequence of strings representing the command as parsed by the shell. Example: "/bin/ls -l" or #["/bin/ls", "-l"]

Note

On Windows this must be a <string>, never a sequence of strings.
under-shell? (#key) – An instance of <boolean>. If true (the default), use a shell to invoke the command. On Unix systems this is equivalent to /bin/sh -c '...command...'. On Windows the COMSPEC environment variable specifies which command interpreter to use.
inherit-console? (#key) – An instance of <boolean>. Whether to run in the same session and process group as the calling process and therefore retain the same controlling TTY. Essentially, whether or not to call setsid(). If you want the subprocess to be a daemon process, pass #f. The default is #t.
outputter (#key) – An instance of <function>. A function with signature (buffer :: <string>, #key end) which will receive all output (both stdout and stderr) from the command.
asynchronous? (#key) – An instance of <boolean>. If true, return immediately after creating the process. Otherwise, block until the command completes or is terminated by signal.
environment (#key) – #f or an instance of <explicit-key-collection>. A table mapping environment variable names (strings) to values (also strings). These values augment the environment in the current process. (There is currently no way to specify via this API that environment should be the only environment variables set in the subprocess.)
working-directory (#key) – #f or an instance of <pathname>. If not #f, the working directory of the subprocess is set to this directory.
input (#key) –
An instance of <pathname> or one of the following symbols:
- #"inherit": Inherit standard input from the calling process. Write to *standard-input* to send input to the subprocess.
- #"null": Use a null stream as standard input.
- #"stream": Create and return a stream connected to the subprocess’s standard input.
- A <pathname>: Open the specified file for reading and connect it to the subprocess’s standard input.
if-input-does-not-exist (#key) –
Either #"signal" or #"create". The default is #signal.
- #"signal": Signal a <file-does-not-exist-error> if input is a pathname that names a non-existent file.
- #"create": Create an empty input file and connect it to standard input of the subprocess.
output (#key) –
An instance of <pathname> or one of the following symbols:
- #"inherit": Inherit standard output from the calling process.
- #"null": Send standard output to a null stream.
- #"stream": Create and return a stream connected to the subprocess’s standard output.
- A <pathname>: Open the specified file for writing and connect it to the subprocess’s standard output.
if-output-exists (#key) – As for the if-exists option when creating an output <file-stream> except that #f is not allowed.
error (#key) – Possible values are the same as for the output parameter except that they apply to *standard-error*.
if-error-exists (#key) – As for the if-exists option when creating an output <file-stream> except that #f is not allowed.
activate? (#key) – An instance of <boolean>. If the activate? argument is #t, the shell window becomes the active window. The default is #t. (Ignored on Unix platforms.)
minimize? (#key) – An instance of <boolean>. If #t, the command’s shell window will appear minimized. The default is #f. (Ignored on Unix platforms.)
hide? (#key) – An instance of <boolean>. If #t, the window associated with this process will be hidden. The default is #f. (Ignored on Unix platforms.)

Values:

status – An instance of <integer>. The exit status returned by waitpid (Unix) or WaitForSingleObject (Windows).
signal – #f or an instance of <integer>. If the process was terminated by a signal this value is the signal number.
process – #f or an instance of <application-process>. If asynchronous? is true, run-application returns immediately and this value identifies the running process. See wait-for-application-process, which may be used to wait for this process to terminate.
#rest streams – Instances of <stream>. Up to three streams are returned, always in the order stdin, stdout, stderr. For example, if the arguments were input: #"null", output: #"stream", error: #"stream" then two streams are returned: output and error.

Discussion:

Launches an application in a new process, using the name and arguments specified in command.

Perhaps the simplest example is to run a command synchronously, with all input/output inherited from the parent shell and only looking at the exit status return value:

let exit-status = run-application("/bin/ls foo");
if (~zero?(exit-status))
  error("/bin/ls failed with status %d", exit-status);
end;

See also:

exit-application
wait-for-application-process

wait-for-application-process Function¶

Waits for a process to terminate.

Signature:

wait-format-application-process process => status signal

Parameters:

process – An instance of <application-process>.

Values:

status – An instance of <integer>. The exit status returned by waitpid (Unix) or WaitForSingleObject (Windows).
signal – #f or an instance of <integer>. If the process was terminated by a signal this value is the signal number.