gleam/erlexec

OS shell command runner. It communicates with a separate C++ port process exec-port spawned by this module, which is responsible for starting, killing, listing, terminating, and notifying of state changes.

For more detailed documentation, please refer to https://hexdocs.pm/erlexec/exec.html

Types

Command

</>

Command to be executed.

pub type Command {
  Shell(String)
  Execve(List(String))
}

Constructors

```
Shell(String)
```
The specified command will be executed through the shell. The current shell is obtained from environment variable SHELL.

This can be useful 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.

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.
```
Execve(List(String))
```
Command is passed to execve(3) library call directly without involving the shell process, so the list of strings represents the program to be executed with arguments. In this case all shell-based features are disabled and there’s no shell injection vulnerability.

EnvOption

</>

pub type EnvOption {
  EnvString(String)
  EnvClear
  EnvKV(String, String)
  EnvUnset(String)
}

Constructors

```
EnvString(String)
```
```
EnvClear
```
```
EnvKV(String, String)
```
```
EnvUnset(String)
```

EnvOptions

</>

pub type EnvOptions =
  List(EnvOption)

ExitStatusOrSignal

</>

pub type ExitStatusOrSignal {
  ExitStatus(Int)
  Signal(status: Signal, core_dump: Bool)
}

Constructors

```
ExitStatus(Int)
```
```
Signal(status: Signal, core_dump: Bool)
```

FindExecutableError

</>

pub type FindExecutableError {
  ExecutableNotFound
}

Constructors

```
ExecutableNotFound
```

ObtainError

</>

pub type ObtainError {
  ObtainTimeout
  ObtainDownStatus(Pid, OsPid, Int)
}

Constructors

```
ObtainTimeout
```
```
ObtainDownStatus(Pid, OsPid, Int)
```

ObtainOk

</>

pub type ObtainOk {
  ObtainStdout(Int, String)
  ObtainStderr(Int, String)
  ObtainDown(Pid, OsPid)
}

Constructors

```
ObtainStdout(Int, String)
```
```
ObtainStderr(Int, String)
```
```
ObtainDown(Pid, OsPid)
```

Options

</>

Keeps track of all the options that will be passed to run_async or run_sync

pub opaque type Options

OsGid

</>

Representation of OS group ID

pub type OsGid =
  Int

OsPid

</>

Representation of OS process ID

pub type OsPid =
  Int

Output

</>

pub type Output {
  Output(List(StdoutOrStderr))
}

Constructors

```
Output(List(StdoutOrStderr))
```

Pids

</>

pub type Pids {
  Pids(Pid, OsPid)
}

Constructors

```
Pids(Pid, OsPid)
```
Pid is the Erlang process identifier. OsPid is the OS process identifier of the new process.

PtyOption

</>

For documentation please check:

pub type PtyOption {
  Vintr(Int)
  Vquit(Int)
  Verase(Int)
  Vkill(Int)
  Veof(Int)
  Veol(Int)
  Veol2(Int)
  Vstart(Int)
  Vstop(Int)
  Vsusp(Int)
  Vdsusp(Int)
  Vreprint(Int)
  Vwerase(Int)
  Vlnext(Int)
  Vflush(Int)
  Vswtch(Int)
  Vstatus(Int)
  Vdiscard(Int)
  Ignpar(Bool)
  Parmrk(Bool)
  Inpck(Bool)
  Istrip(Bool)
  Inlcr(Bool)
  Igncr(Bool)
  Icrnl(Bool)
  Xcase(Bool)
  Iuclc(Bool)
  Ixon(Bool)
  Ixany(Bool)
  Ixoff(Bool)
  Imaxbel(Bool)
  Iutf8(Bool)
  Isig(Bool)
  Icanon(Bool)
  Echo(Bool)
  Echoe(Bool)
  Echok(Bool)
  Echonl(Bool)
  Noflsh(Bool)
  Tostop(Bool)
  Iexten(Bool)
  Echoctl(Bool)
  Echoke(Bool)
  Pendin(Bool)
  Opost(Bool)
  Olcuc(Bool)
  Onlcr(Bool)
  Ocrnl(Bool)
  Onocr(Bool)
  Onlret(Bool)
  Cs7(Bool)
  Cs8(Bool)
  Parenb(Bool)
  Parodd(Bool)
  TtyOpIspeed(Int)
  TtyOpOspeed(Int)
}

Constructors

```
Vintr(Int)
```
```
Vquit(Int)
```
```
Verase(Int)
```
```
Vkill(Int)
```
```
Veof(Int)
```
```
Veol(Int)
```
```
Veol2(Int)
```
```
Vstart(Int)
```
```
Vstop(Int)
```
```
Vsusp(Int)
```
```
Vdsusp(Int)
```
```
Vreprint(Int)
```
```
Vwerase(Int)
```
```
Vlnext(Int)
```
```
Vflush(Int)
```
```
Vswtch(Int)
```
```
Vstatus(Int)
```
```
Vdiscard(Int)
```
```
Ignpar(Bool)
```
```
Parmrk(Bool)
```
```
Inpck(Bool)
```
```
Istrip(Bool)
```
```
Inlcr(Bool)
```
```
Igncr(Bool)
```
```
Icrnl(Bool)
```
```
Xcase(Bool)
```
```
Iuclc(Bool)
```
```
Ixon(Bool)
```
```
Ixany(Bool)
```
```
Ixoff(Bool)
```
```
Imaxbel(Bool)
```
```
Iutf8(Bool)
```
```
Isig(Bool)
```
```
Icanon(Bool)
```
```
Echo(Bool)
```
```
Echoe(Bool)
```
```
Echok(Bool)
```
```
Echonl(Bool)
```
```
Noflsh(Bool)
```
```
Tostop(Bool)
```
```
Iexten(Bool)
```
```
Echoctl(Bool)
```
```
Echoke(Bool)
```
```
Pendin(Bool)
```
```
Opost(Bool)
```
```
Olcuc(Bool)
```
```
Onlcr(Bool)
```
```
Ocrnl(Bool)
```
```
Onocr(Bool)
```
```
Onlret(Bool)
```
```
Cs7(Bool)
```
```
Cs8(Bool)
```
```
Parenb(Bool)
```
```
Parodd(Bool)
```
```
TtyOpIspeed(Int)
```
```
TtyOpOspeed(Int)
```

PtyOptions

</>

pub type PtyOptions {
  PtyEnable
  PtyOpts(List(PtyOption))
}

Constructors

```
PtyEnable
```
```
PtyOpts(List(PtyOption))
```

Signal

</>

pub type Signal {
  SIGHUP
  SIGINT
  SIGQUIT
  SIGILL
  SIGTRAP
  SIGABRT
  SIGBUS
  SIGFPE
  SIGKILL
  SIGUSR1
  SIGSEGV
  SIGUSR2
  SIGPIPE
  SIGALRM
  SIGTERM
  SIGSTKFLT
  SIGCHLD
  SIGCONT
  SIGSTOP
  SIGTSTP
  SIGTTIN
  SIGTTOU
  SIGURG
  SIGXCPU
  SIGXFSZ
  SIGVTALRM
  SIGPROF
  SIGWINCH
  SIGIO
  SIGPWR
  SIGSYS
  Other(Int)
}

Constructors

```
SIGHUP
```
```
SIGINT
```
```
SIGQUIT
```
```
SIGILL
```
```
SIGTRAP
```
```
SIGABRT
```
```
SIGBUS
```
```
SIGFPE
```
```
SIGKILL
```
```
SIGUSR1
```
```
SIGSEGV
```
```
SIGUSR2
```
```
SIGPIPE
```
```
SIGALRM
```
```
SIGTERM
```
```
SIGSTKFLT
```
```
SIGCHLD
```
```
SIGCONT
```
```
SIGSTOP
```
```
SIGTSTP
```
```
SIGTTIN
```
```
SIGTTOU
```
```
SIGURG
```
```
SIGXCPU
```
```
SIGXFSZ
```
```
SIGVTALRM
```
```
SIGPROF
```
```
SIGWINCH
```
```
SIGIO
```
```
SIGPWR
```
```
SIGSYS
```
```
Other(Int)
```

StartError

</>

pub type StartError {
  AlreadyStarted(Pid)
}

Constructors

```
AlreadyStarted(Pid)
```

StartOption

</>

pub type StartOption {
  StartDebug(level: Int)
  StartRoot(enable: Bool)
  StartVerbose
  StartArgs(List(String))
  StartAlarm(seconds: Int)
  StartUser(String)
  StartLimitUsers(List(String))
  StartPortexe(String)
  StartEnv(EnvOptions)
}

Constructors

```
StartDebug(level: Int)
```
```
StartRoot(enable: Bool)
```
```
StartVerbose
```
```
StartArgs(List(String))
```
```
StartAlarm(seconds: Int)
```
```
StartUser(String)
```
```
StartLimitUsers(List(String))
```
```
StartPortexe(String)
```
```
StartEnv(EnvOptions)
```

StderrOptions

</>

pub type StderrOptions {
  StderrCapture
  StderrClose
  StderrFun(fn(Atom, Int, String) -> Nil)
  StderrNull
  StderrPid(Pid)
  StderrPrint
  StderrStdout
  StderrString(String)
}

Constructors

```
StderrCapture
```
```
StderrClose
```
```
StderrFun(fn(Atom, Int, String) -> Nil)
```
```
StderrNull
```
```
StderrPid(Pid)
```
```
StderrPrint
```
```
StderrStdout
```
```
StderrString(String)
```

StdinOptions

</>

pub type StdinOptions {
  StdinClose
  StdinNull
  StdinPipe
  StdinFrom(String)
}

Constructors

```
StdinClose
```
```
StdinNull
```
```
StdinPipe
```
```
StdinFrom(String)
```

StdoutOptions

</>

pub type StdoutOptions {
  StdoutCapture
  StdoutClose
  StdoutFun(fn(Atom, Int, String) -> Nil)
  StdoutNull
  StdoutPid(Pid)
  StdoutPrint
  StdoutStderr
  StdoutString(String)
}

Constructors

```
StdoutCapture
```
```
StdoutClose
```
```
StdoutFun(fn(Atom, Int, String) -> Nil)
```
```
StdoutNull
```
```
StdoutPid(Pid)
```
```
StdoutPrint
```
```
StdoutStderr
```
```
StdoutString(String)
```

StdoutOrStderr

</>

pub type StdoutOrStderr {
  Stdout(List(String))
  Stderr(List(String))
}

Constructors

```
Stdout(List(String))
```
```
Stderr(List(String))
```

StopError

</>

pub type StopError {
  NoProcess
}

Constructors

```
NoProcess
```

Functions

debug

</>

pub fn debug(level: Int) -> Result(Int, Atom)

Set the global debug level

find_executable

</>

pub external fn find_executable(
  name: String,
) -> Result(String, FindExecutableError)

Tries to find the given executable name and returns the full path to it.

get_cd

</>

pub fn get_cd(options: Options) -> Option(String)

get_env

</>

pub fn get_env(options: Options) -> List(EnvOption)

get_executable

</>

pub fn get_executable(options: Options) -> Option(String)

get_kill

</>

pub fn get_kill(options: Options) -> Option(String)

get_link

</>

pub fn get_link(options: Options) -> Bool

get_monitor

</>

pub fn get_monitor(options: Options) -> Bool

get_pty

</>

pub fn get_pty(options: Options) -> Bool

get_stderr

</>

pub fn get_stderr(options: Options) -> Option(StderrOptions)

get_stdin

</>

pub fn get_stdin(options: Options) -> Option(StdinOptions)

get_stdout

</>

pub fn get_stdout(options: Options) -> Option(StdoutOptions)

int_to_signal

</>

pub fn int_to_signal(signal: Int) -> Signal

kill_ospid

</>

pub fn kill_ospid(ospid: Int, signal: Int) -> Result(Nil, Dynamic)

Send a signal to an OsPid.

kill_pid

</>

pub fn kill_pid(pid: Pid, signal: Int) -> Result(Nil, Dynamic)

Send a signal to a child Pid.

manage_pid

</>

pub fn manage_pid(pid: Pid, options: Options) -> Dynamic

new

</>

pub fn new() -> Options

Initial constructor for Options. Changing these settings is done with the with_* functions.

obtain

</>

pub external fn obtain(
  timeout_in_milliseconds: Int,
) -> Result(ObtainOk, ObtainError)

options_to_list

</>

pub fn options_to_list(options: Options) -> List(Dynamic)

run_async

</>

pub fn run_async(options: Options, command: Command) -> Result(
  Pids,
  String,
)

Run command with the given options, don’t wait for it to finish.

run_sync

</>

pub fn run_sync(options: Options, command: Command) -> Result(
  Output,
  String,
)

Run command with the given options, block the caller until it exits.

send

</>

pub fn send(ospid: Int, data: String) -> Result(Nil, Dynamic)

send_eof

</>

pub fn send_eof(ospid: Int) -> Result(Nil, Dynamic)

This will close stdin.

signal_to_int

</>

pub fn signal_to_int(signal: Signal) -> Int

start

</>

pub fn start(options: List(StartOption)) -> Result(
  Pid,
  StartError,
)

Start the exec application

status

</>

pub fn status(status: Int) -> ExitStatusOrSignal

Decode the program’s exit_status.

If the program exited by signal the function returns Signal, otherwise it will return an ExitStatus

stop

</>

pub fn stop(pid: Int) -> Result(Nil, Dynamic)

Terminate a managed Pid, OsPid, or Port process. The OS process is terminated gracefully. If it was given a {kill, Cmd} option at startup, that command is executed and a timer is started. If the program doesn’t exit, then the default termination is performed. Default termination implies sending a SIGTERM command followed by a SIGKILL in 5 seconds, if the program doesn’t get killed.

to_ospid

</>

pub fn to_ospid(ospid: Pid) -> Result(Int, Dynamic)

which_children

</>

pub external fn which_children() -> List(OsPid)

Get a list of children OsPids managed by the port program.

winsz

</>

pub fn winsz(pid: Int, rows: Int, columns: Int) -> Result(
  Nil,
  Nil,
)

with_cd

</>

pub fn with_cd(old: Options, given: String) -> Options

Set a working directory

with_debug

</>

pub fn with_debug(old: Options, level: Int) -> Options

Configure debug printing for this command.

The level should be 0 <= level =< 10

with_env

</>

pub fn with_env(old: Options, given: List(EnvOption)) -> Options

Modify the program environment. See EnvOption

with_executable

</>

pub fn with_executable(old: Options, given: String) -> Options

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 the command argument is specified as the list of strings, the executable replaces the first parameter in the call, and the original args provided in the command 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.

Unix specific:

The args name becomes the display name for the executable in utilities such as ps.

If the command argument is a Shell, the Executable specifies a replacement shell for the default /bin/sh.

with_group

</>

pub fn with_group(old: Options, given: Int) -> Options

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.

with_kill

</>

pub fn with_kill(old: Options, command: String) -> Options

This command will be used for killing the process.

If the process is still alive after 5 seconds, it receives a 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.

with_kill_group

</>

pub fn with_kill_group(old: Options, given: Bool) -> Options

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

with_kill_timeout

</>

pub fn with_kill_timeout(old: Options, given: Int) -> Options

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

with_link

</>

pub fn with_link(old: Options, given: Bool) -> Options

Link to the OsPid. If OsPid exits, the calling process will be killed or if it’s trapping exits, it’ll get {‘EXIT’, OsPid, Status} message. If the calling process dies the OsPid will be killed. The Status can be decoded with status to determine the process’s exit code and if it was killed by signal.

with_monitor

</>

pub fn with_monitor(old: Options, given: Bool) -> Options

Set up a monitor for the spawned process.

The monitor is not a standard erlang:monitor/2 function call, but it’s emulated by ensuring that the monitoring process receives notifications 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 the status function to determine the exit code of the process and if it was killed by signal.

with_nice

</>

pub fn with_nice(old: Options, priority: Int) -> Options

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.

with_pty

</>

pub fn with_pty(old: Options, enable_pty: Bool) -> Options

Use pseudo terminal for the process’s stdin, stdout and stderr

with_pty_echo

</>

pub fn with_pty_echo(old: Options, given: Bool) -> Options

Allow the pty to run in echo mode, disabled by default.

with_stderr

</>

pub fn with_stderr(old: Options, given: StderrOptions) -> Options

Configure stderr communication with the OS process. See StderrOptions

with_stdin

</>

pub fn with_stdin(old: Options, given: StdinOptions) -> Options

Configure stdin communication with the OS process. See StdinOptions

with_stdout

</>

pub fn with_stdout(old: Options, given: StdoutOptions) -> Options

Configure stdout communication with the OS process. See StdoutOptions

with_success_exit_code

</>

pub fn with_success_exit_code(old: Options, given: Int) -> Options

Return value on success.

with_user

</>

pub fn with_user(old: Options, given: String) -> Options

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 effective user. The value “root” is prohibited.

with_winsz

</>

pub fn with_winsz(old: Options, rows: Int, columns: Int) -> Options