-type cmd() :: binary() | string() | [string()].

Command to be executed. If specified as a string, the specified command will be executed through the shell. The current shell is obtained from environment variable SHELL. This can be useful if you are using Erlang primarily for the enhanced control flow it offers over most system shells and still want convenient access to other shell features such as shell pipes, filename wildcards, environment variable expansion, and expansion of ~ to a user's home directory. All command arguments must be properly escaped including whitespace and shell metacharacters.

Any part of the command string can contain unicode characters.

Warning: Executing shell commands that incorporate unsanitized input from an untrusted source makes a program vulnerable to shell injection, a serious security flaw which can result in arbitrary command execution. For this reason, the use of shell is strongly discouraged in cases where the command string is constructed from external input:

 1> {ok, Filename} = io:read("Enter filename: ").
 Enter filename: "non_existent; rm -rf / #".
 {ok, "non_existent; rm -rf / #"}
 2> exec(Filename, []) % Argh!!! This is not good!

When command is given in the form of a list of strings, it is passed to execve(3) library call directly without involving the shell process, so the list of strings represents the program to be executed given with a full path, followed by the list of arguments (e.g. ["/bin/echo", "ok"]). In this case all shell-based features are disabled and there's no shell injection vulnerability.

-type cmd_option() ::
    monitor | sync | link |
    {executable, string() | binary()} |
    {cd, WorkDir :: string() | binary()} |
    {env,
     [string() | clear | {Name :: string() | binary(), Val :: string() | binary() | false}, ...]} |
    {kill, KillCmd :: string() | binary()} |
    {kill_timeout, Sec :: non_neg_integer()} |
    kill_group |
    {group, GID :: string() | binary() | integer()} |
    {user, RunAsUser :: string() | binary()} |
    {nice, Priority :: integer()} |
    {success_exit_code, ExitCode :: integer()} |
    stdin |
    {stdin, null | close | string() | binary()} |
    stdout | stderr |
    {stdout, stderr | output_dev_opt()} |
    {stderr, stdout | output_dev_opt()} |
    {stdout | stderr, string() | binary(), [output_file_opt()]} |
    {winsz, {Rows :: non_neg_integer(), Cols :: non_neg_integer()}} |
    pty |
    {pty, pty_opts()} |
    pty_echo | debug |
    {debug, integer()}.

Command options:

• monitor : Set up a monitor for the spawned process. The monitor is not a standard erlang:montior/2 function call, but it's emulated by ensuring that the monitoring process receives notification in the form: {'DOWN', OsPid::integer(), process, Pid::pid(), Reason}. If the Reason is normal, then process exited with status 0, otherwise there was an error. If the Reason is {status, Status} the returned Status can be decoded with status/1 to determine the exit code of the process and if it was killed by signal.

• sync : Block the caller until the OS command exits

• {executable, Executable::string()} : Specifies a replacement program to execute. It is very seldom needed. When the port program executes a child process using execve(3) call, the call takes the following arguments: (Executable, Args, Env). When Cmd argument passed to the run/2 function is specified as the list of strings, the executable replaces the first parameter in the call, and the original args provided in the Cmd parameter are passed as as the second parameter. Most programs treat the program specified by args as the command name, which can then be different from the program actually executed. On Unix, the args name becomes the display name for the executable in utilities such as ps.

  If Cmd argument passed to the run/2 function is given as a string, on Unix the Executable specifies a replacement shell for the default /bin/sh.

• {cd, WorkDir} : Working directory

• {env, Env :: [{Name,Value}|string()|clear]} : List of "VAR=VALUE" environment variables or list of {Name, Value} tuples or strings (like "NAME=VALUE") or clear. clear will clear environment of a spawned child OS process (so that it doesn't inherit parent's environment). If Value is false then the Var env variable is unset.

• {kill, KillCmd} : This command will be used for killing the process. After a 5-sec timeout if the process is still alive, it'll be killed with SIGKILL. The kill command will have a CHILD_PID environment variable set to the pid of the process it is expected to kill. If the kill option is not specified, by default first the command is sent a SIGTERM signal, followed by SIGKILL after a default timeout.

• {kill_timeout, Sec::integer()} : Number of seconds to wait after issuing a SIGTERM or executing the custom kill command (if specified) before killing the process with the SIGKILL signal

• kill_group : At process exit kill the whole process group associated with this pid. The process group is obtained by the call to getpgid(3).

• {group, GID} : Sets the effective group ID of the spawned process. The value 0 means to create a new group ID equal to the OS pid of the process.

• {user, RunAsUser} : When exec-port was compiled with capability (Linux) support enabled and has a suid bit set, it's capable of running commands with a different RunAsUser effective user. Passing "root" value of RunAsUser is prohibited.

• {success_exit_code, IntExitCode} : On success use IntExitCode return value instead of default 0.

• {nice, Priority} : Set process priority between -20 and 20. Note that negative values can be specified only when exec-port is started with a root suid bit set.

• stdin | {stdin, null | close | Filename} : Enable communication with an OS process via its stdin. The input to the process is sent by exec:send(OsPid, Data). When specified as a tuple, null means redirection from /dev/null, close means to close stdin stream, and Filename means to take input from file.

• stdout : Same as {stdout, self()}.

• stderr : Same as {stderr, self()}.

• {stdout, output_device()} : Redirect process's standard output stream

• {stderr, output_device()} : Redirect process's standard error stream

• {stdout | stderr, Filename::string(), [output_dev_opt()]} : Redirect process's stdout/stderr stream to file

• {winsz, {Rows, Cols}} : Set the (psudo) terminal's dimensions of rows and columns

• pty : Use pseudo terminal for the process's stdin, stdout and stderr

• pty_echo : Allow the pty to run in echo mode, disabled by default

• debug : Same as {debug, 1}

• {debug, Level::integer()} : Enable debug printing in port program for this command

-type exec_option() ::
    debug |
    {debug, integer()} |
    root |
    {root, boolean()} |
    verbose |
    {args, [string() | binary(), ...]} |
    {alarm, non_neg_integer()} |
    {user, string() | binary()} |
    {limit_users, [string() | binary(), ...]} |
    {portexe, string() | binary()} |
    {env, [{string() | binary(), string() | binary() | false}, ...]} |
    valgrind |
    {valgrind, string()}.

Options passed to the exec process at startup. They can be specified in the sys.config file for the erlexec application to customize application startup.

• debug : Same as {debug, 1}
• {debug, Level} : Enable port-programs debug trace at Level.
• verbose : Enable verbose prints of the Erlang process.

• root | {root, Boolean} : Allow running child processes as root.

• {args, Args} : Append Args to the port command.
• {alarm, Secs} : Give Secs deadline for the port program to clean up child pids before exiting
• {user, User} : When the port program was compiled with capability (Linux) support enabled, and is owned by root with a a suid bit set, this option must be specified so that upon startup the port program is running under the effective user different from root. This is a security measure that will also prevent the port program to execute root commands.
• {limit_users, LimitUsers} : Limit execution of external commands to these set of users. This option is only valid when the port program is owned by root.
• {portexe, Exe} : Provide an alternative location of the port program. This option is useful when this application is stored on NFS and the port program needs to be copied locally so that root suid bit can be set.
• {env, Env} : Extend environment of the port program by using Env specification. Env should be a list of tuples {Name, Val}, where Name is the name of an environment variable, and Val is the value it is to have in the spawned port process. If Val is false, then the Name environment variable is unset.
• valgrind : Start port-exec by valgrind in order to check for memory and resource leaks. This is only adviseable for testing. For Valgrind support make sure that the tool is installed. Install with:

  sudo apt install valgrind            # Ubuntu, Debian, etc.
  sudo yum install valgrind            # RHEL, CentOS, Fedora, etc.
  sudo pacman -Syu valgrind debuginfod # Arch, Manjaro, Garuda, etc.
  sudo pkg ins valgrind                # FreeBSD

  The Valgrind log will be written to the file valgrind-YYYYMMDDhhmmss.log
• {valgrind, Command} : Same as valgrind, but allows to specify the Valgrind command and its options (e.g. "/path/to/valgrind --leak-check=full")

-type osgid() :: integer().

Representation of OS group ID

-type ospid() :: integer().

Representation of OS process ID

-type output_dev_opt() ::
    null | close | print |
    string() |
    binary() |
    pid() |
    fun((stdout | stderr, integer(), binary()) -> none()).

Output device option:

• null : Suppress output.
• close : Close file descriptor for writing.
• print : A debugging convenience device that prints the output to the console shell
• Filename : Save output to file by overwriting it.
• pid() : Redirect output to this pid.
• fun((Stream, OsPid, Data) -> none()) : Execute this callback on receiving output data

-type output_file_opt() :: append | {mode, Mode :: integer()}.

Defines file opening attributes:

• append : Open the file in append mode
• {mode, Mode} : File creation access mode <b>specified in base 8</b> (e.g. 8#0644)

-type pty_opt() ::
    {tty_char(), byte()} | {tty_mode(), boolean() | 0 | 1} | {tty_speed(), non_neg_integer()}.

Pty options.

See termios(3). See RFC4254.

• {tty_char(), Byte} : A special character with value from 0 to 255
• {tty_mode(), Enable} : Enable/disable a tty mode
• {tty_speed(), Speed} : Specify input or output baud rate. Provided for completeness. Not useful for pseudo terminals.

-type pty_opts() :: [pty_opt()].

List of pty options