-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!

-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()}.

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}, ...]}.

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.

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

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()}.

append

Open the file in append mode

{mode, Mode}

File creation access mode specified in base 8 (e.g. 8#0644)

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

• https://man7.org/linux/man-pages/man3/termios.3.html
• https://datatracker.ietf.org/doc/html/rfc4254#section-8

{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.