System.cmd
cmd
, go back to System module for more information.
Specs
cmd(binary(), [binary()], keyword()) :: {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 binaries which the executable will receive
as its arguments as is. This means that:
- environment variables will not be interpolated
- wildcard expansion will not happen (unless
Path.wildcard/2
is used explicitly) - arguments do not need to be escaped or quoted for shell safety
This function returns a tuple containing the collected result and the command exit status.
Internally, this function uses a Port
for interacting with the
outside world. However, if you plan to run a long-running program,
ports guarantee stdin/stdout devices will be closed but it does not
automatically terminate the program. The documentation for the
Port
module describes this problem and possible solutions under
the "Zombie processes" section.
Examples
iex> System.cmd("echo", ["hello"])
{"hello\n", 0}
iex> System.cmd("echo", ["hello"], env: [{"MIX_ENV", "test"}])
{"hello\n", 0}
If you want to stream the devices to IO as they come:
iex> System.cmd("echo", ["hello"], into: IO.stream())
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. The child process inherits all environment variables from its parent process, the Elixir application, except those overwritten or cleared using this option. Specify a value ofnil
to clear (unset) an environment variable, which is useful for preventing credentials passed to the application from leaking into child processes.:arg0
- sets 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 shell/2
.