Elixir v1.1.0 System
The System module provides access to variables used or maintained by the VM and to functions that interact directly with the VM or the host system.
Summary
Functions
Lists command line arguments
Modifies command line arguments
Registers a program exit handler function
Elixir build information
Executes the given command
with args
Current working directory
Current working directory, exception on error
Deletes an environment variable
Locates an executable on the system
System environment variables
Environment variable value
Erlang VM process identifier
Halts the Erlang runtime system
Sets multiple environment variables
Sets an environment variable value
Last exception stacktrace
Writable temporary directory
Writable temporary directory, exception on error
User home directory
User home directory, exception on error
Elixir version information
Functions
Specs
argv :: [String.t]
Lists command line arguments.
Returns the list of command line arguments passed to the program.
Specs
argv([String.t]) :: :ok
Modifies command line arguments.
Changes the list of command line arguments. Use it with caution, as it destroys any previous argv information.
Registers a program exit handler function.
Registers a function that will be invoked at the end of program execution. Useful for invoking a hook in “script” mode.
The handler always executes in a different process from the one it was registered in. As a consequence, any resources managed by the calling process (ETS tables, open files, etc.) won’t be available by the time the handler function is invoked.
The function must receive the exit status code as an argument.
Specs
build_info :: map
Elixir build information.
Returns a keyword list with Elixir version, git tag info and compilation date.
Specs
cmd(binary, [binary], Keyword.t) :: {Collectable.t, exit_status :: non_neg_integer}
Executes the given command
with args
.
command
is expected to be an executable available in PATH
unless an absolute path is given.
args
must be a list of strings which are not expanded
in any way. For example, this means wildcard expansion will
not happen unless Path.wildcard/2
is used. On Windows though,
wildcard expansion is up to the program.
This function returns a tuple containing the collected result and the command exit status.
Examples
iex> System.cmd "echo", ["hello"]
{"hello\n", 0}
iex> System.cmd "echo", ["hello"], env: [{"MIX_ENV", "test"}]
{"hello\n", 0}
iex> System.cmd "echo", ["hello"], into: IO.stream(:stdio, :line)
hello
{%IO.Stream{}, 0}
Options
:into
- injects the result into the given collectable, defaults to""
:cd
- the directory to run the command in:env
- an enumerable of tuples containing environment key-value as binary:arg0
- set the command arg0:stderr_to_stdout
- redirects stderr to stdout whentrue
:parallelism
- whentrue
, the VM will schedule port tasks to improve parallelism in the system. If set tofalse
, the VM will try to perform commands immediately, improving latency at the expense of parallelism. The default can be set on system startup by passing the “+spp” argument to--erl
.
Error reasons
If invalid arguments are given, ArgumentError
is raised by
System.cmd/3
. System.cmd/3
also expects a strict set of
options and will raise if unknown or invalid options are given.
Furthermore, System.cmd/3
may fail with one of the POSIX reasons
detailed below:
:system_limit
- all available ports in the Erlang emulator are in use:enomem
- there was not enough memory to create the port:eagain
- there are no more available operating system processes:enametoolong
- the external command given was too long:emfile
- there are no more available file descriptors (for the operating system process that the Erlang emulator runs in):enfile
- the file table is full (for the entire operating system):eacces
- the command does not point to an executable file:enoent
- the command does not point to an existing file
Shell commands
If you desire to execute a trusted command inside a shell, with pipes,
redirecting and so on, please check
:os.cmd/1
.
Current working directory.
Returns the current working directory or nil
if one
is not available.
Current working directory, exception on error.
Returns the current working directory or raises RuntimeError
.
Specs
delete_env(String.t) :: :ok
Deletes an environment variable.
Removes the variable varname
from the environment.
Specs
find_executable(binary) :: binary | nil
Locates an executable on the system.
This function looks up an executable program given
its name using the environment variable PATH on Unix
and Windows. It also considers the proper executable
extension for each OS, so for Windows it will try to
lookup files with .com
, .cmd
or similar extensions.
System environment variables.
Returns a list of all environment variables. Each variable is given as a
{name, value}
tuple where both name
and value
are strings.
Specs
get_env(binary) :: binary | nil
Environment variable value.
Returns the value of the environment variable
varname
as a binary, or nil
if the environment
variable is undefined.
Specs
get_pid :: binary
Erlang VM process identifier.
Returns the process identifier of the current Erlang emulator in the format most commonly used by the operating system environment.
For more information, see :os.getpid/0
.
Specs
halt(non_neg_integer | binary | :abort) :: no_return
Halts the Erlang runtime system.
Halts the Erlang runtime system where the argument status
must be a
non-negative integer, the atom :abort
or a binary.
If an integer, the runtime system exits with the integer value which is returned to the operating system.
If
:abort
, the runtime system aborts producing a core dump, if that is enabled in the operating system.- If a string, an Erlang crash dump is produced with status as slogan, and then the runtime system exits with status code 1.
Note that on many platforms, only the status codes 0-255 are supported by the operating system.
For more information, see :erlang.halt/1
.
Examples
System.halt(0)
System.halt(1)
System.halt(:abort)
Specs
put_env(Dict.t) :: :ok
Sets multiple environment variables.
Sets a new value for each environment variable corresponding
to each key in dict
.
Specs
put_env(binary, binary) :: :ok
Sets an environment variable value.
Sets a new value
for the environment variable varname
.
Last exception stacktrace.
Note that the Erlang VM (and therefore this function) does not return the current stacktrace but rather the stacktrace of the latest exception.
Inlined by the compiler into :erlang.get_stacktrace/0
.
Writable temporary directory.
Returns a writable temporary directory. Searches for directories in the following order:
- the directory named by the TMPDIR environment variable
- the directory named by the TEMP environment variable
- the directory named by the TMP environment variable
C:\TMP
on Windows or/tmp
on Unix- as a last resort, the current working directory
Returns nil
if none of the above are writable.
Writable temporary directory, exception on error.
Same as tmp_dir/0
but raises RuntimeError
instead of returning nil
if no temp dir is set.
User home directory, exception on error.
Same as user_home/0
but raises RuntimeError
instead of returning nil
if no user home is set.