System.cmd

You're seeing just the function cmd, go back to System module for more information.
Link to this function

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

View Source

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 of nil 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 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 shell/2.