Elixir v1.2.6 System

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.

build_info()

build_info() :: map

Elixir build information.

Returns a keyword list with Elixir version, git short revision hash and compilation date.

cmd(command, args, opts \\ [])

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 when true
:parallelism - when true, the VM will schedule port tasks to improve parallelism in the system. If set to false, 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.

compiled_endianness()

Returns the endianness the system was compiled with.

convert_time_unit(time, from_unit, to_unit)

convert_time_unit(integer, :erlang.time_unit, :erlang.time_unit) :: integer

Converts time from time unit from_unit to time unit to_unit. The result is rounded via the floor function.

Inlined by the compiler into :erlang.convert_time_unit/3.

cwd()

Current working directory.

Returns the current working directory or nil if one is not available.

cwd!()

Current working directory, exception on error.

Returns the current working directory or raises RuntimeError.

delete_env(varname)

delete_env(String.t) :: :ok

Deletes an environment variable.

Removes the variable varname from the environment.

endianness()

Returns the endianness.

find_executable(program)

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.

get_env()

get_env() :: %{String.t => String.t}

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.

get_env(varname)

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.

get_pid()

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.

halt(status \\ 0)

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)

monotonic_time()

monotonic_time() :: integer

Returns the current monotonic time in the :native time unit.

This time is monotonically increasing and starts in an unspecified point in time.

For more information, see the chapter on time and time correction in the Erlang docs.

Inlined by the compiler into :erlang.monotonic_time/0.

monotonic_time(unit)

monotonic_time(:erlang.time_unit) :: integer

Returns the current monotonic time in the given time unit.

For more information, see the chapter on time and time correction in the Erlang docs.

Inlined by the compiler into :erlang.monotonic_time/1.

put_env(enum)

put_env(Enumerable.t) :: :ok

Sets multiple environment variables.

Sets a new value for each environment variable corresponding to each key in dict.

put_env(varname, value)

put_env(binary, binary) :: :ok

Sets an environment variable value.

Sets a new value for the environment variable varname.

stacktrace()

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.

system_time()

system_time() :: integer

Returns the current system time in the :native time unit.

For more information, see the chapter on time and time correction in the Erlang docs.

Inlined by the compiler into :erlang.system_time/0.

system_time(unit)

system_time(:erlang.time_unit) :: integer

Returns the current system time in the given time unit.

For more information, see the chapter on time and time correction in the Erlang docs.

Inlined by the compiler into :erlang.system_time/1.

time_offset()

time_offset() :: integer

Returns the current time offset between the Erlang monotonic time and the Erlang system time.

The result is returned in the :native time unit.

See time_offset/1 for more information.

Inlined by the compiler into :erlang.time_offset/0.

time_offset(unit)

time_offset(:erlang.time_unit) :: integer

Returns the current time offset between the Erlang monotonic time and the Erlang system time.

The result is returned in the given time unit unit. The returned offset, added to an Erlang monotonic time (e.g., obtained with monotonic_time/1, gives the Erlang system time that corresponds to that monotonic time.

For more information, see the chapter on time and time correction in the Erlang docs.

Inlined by the compiler into :erlang.time_offset/1.

tmp_dir()

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.

tmp_dir!()

Writable temporary directory, exception on error.

Same as tmp_dir/0 but raises RuntimeError instead of returning nil if no temp dir is set.

unique_integer(modifiers \\ [])

unique_integer([:positive | :monotonic]) :: integer

Generates and returns an integer that is unique in the current runtime instance.

“Unique” means that this function, called with the same list of modifiers, will never return the same integer more than once on the current runtime instance.

If modifiers is [], then an unique integer (that can be positive or negative) is returned. Other modifiers can be passed to change the properties of the returned integer:

:positive - the returned integer is guaranteed to be positive.
:monotonic - the returned integer is monotonically increasing. This means that, on the same runtime instance (but even on different processes), integers returned using the :monotonic modifier will always be strictly less than integers returned by successive calls with the :monotonic modifier.

All modifiers listed above can be combined; repeated modifiers in modifiers will be ignored.

Inlined by the compiler into :erlang.unique_integer/1.

user_home()

User home directory.

Returns the user home directory (platform independent).

user_home!()

User home directory, exception on error.

Same as user_home/0 but raises RuntimeError instead of returning nil if no user home is set.

version()

version() :: String.t

Elixir version information.

Returns Elixir’s version as binary.