View Source ExPTY (ExPTY v0.2.1)

forkpty(3) bindings for Elixir.

This allows you to fork processes with pseudoterminal file descriptors.

It returns a terminal genserver which allows reads and writes.

Summary

Functions

Convert argc/argv into a Win32 command-line following the escaping convention documented on MSDN (e.g. see CommandLineToArgvW documentation). Copied from winpty and node-pty project.

Returns a specification to start this module under a supervisor.

Default options when spawning a process.

Get flow control status (only available on Unix systems at the moment).

Set flow control status (only available on Unix systems at the moment).

Kill the process with given signal.

Set callback function or module when data is available from the pseudoterminal.

Set callback function or module when the process exited.

Pause flow (only available on Unix systems at the moment).

Resize the pseudoterminal.

Resume flow (only available on Unix systems at the moment).

Forks a process as a pseudoterminal.

Write data to the pseudoterminal.

Functions

Link to this function

args_to_command_line(file, args)

View Source

Convert argc/argv into a Win32 command-line following the escaping convention documented on MSDN (e.g. see CommandLineToArgvW documentation). Copied from winpty and node-pty project.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec default_pty_options() :: Keyword.t()

Default options when spawning a process.

Please see ExPTY.spawn/3 for details.

@spec flow_control(pid()) :: boolean()

Get flow control status (only available on Unix systems at the moment).

Link to this function

flow_control(pty, enable?)

View Source
@spec flow_control(pid(), boolean()) :: :ok

Set flow control status (only available on Unix systems at the moment).

@spec kill(pid(), integer()) :: :ok

Kill the process with given signal.

@spec on_data(pid(), atom() | (ExPTY, pid(), binary() -> any())) :: :ok

Set callback function or module when data is available from the pseudoterminal.

@spec on_exit(pid(), atom() | (ExPTY, pid(), integer(), integer() | nil -> any())) ::
  :ok

Set callback function or module when the process exited.

@spec pause(pid()) :: :ok

Pause flow (only available on Unix systems at the moment).

@spec resize(pid(), pos_integer(), pos_integer()) :: :ok | {:error, String.t()}

Resize the pseudoterminal.

@spec resume(pid()) :: :ok

Resume flow (only available on Unix systems at the moment).

Link to this function

spawn(file, args, opts \\ [])

View Source
@spec spawn(String.t(), [String.t()], keyword()) ::
  {:ok, pid()} | {:error, String.t()}

Forks a process as a pseudoterminal.

Positional Paramters
  • file: String.t()

    The file to launch.

  • args: list(String.t())

    The file's arguments as argv (const char * []).

Keyword Parameters
Common Keyword Parameters (Unix & Windows)
  • name: String.t()

    Terminal name.

    Defaults to xterm-color on Unix systems and Windows Shell on Windows.

  • cols: pos_integer()

    Number of columns.

    Defaults to 80.

  • rows: pos_integer()

    Number of rows.

    Defaults to 24.

  • ibaudrate: non_neg_integer()

    cfsetispeed(term, ibaudrate)

    Defaults to 38400.

  • obaudrate: non_neg_integer()

    cfsetospeed(term, obaudrate)

    Defaults to 38400.

  • env: %{String.t() => String.t()}

    Environment variables.

    Defaults to System.get_env().

    Notice, as the default value is given by System.get_env(), therefore, please be careful of leaking secrets set in the environment.

  • cwd: String.t()

    Current working directory.

    Defaults to Path.expand("~").

  • on_data: (ExPTY, pid(), binary() -> term()) | atom

    Callback when data is available.

    Defaults to nil.

    When passing a function, the function should expect 3 arguments,

    1. ExPTY: The module name of ExPTY. This will probably be removed in the first release.
    2. pid(): The genserver pid so that you can reuse the same function for different processes spawned.
    3. binary(): The data read from the spawned process.

    When passing a module name, the module should export an on_data/3 function, this function should expect the same arguments as mentioned above.

    The return value of this callback function is ignored.

  • on_exit: (ExPTY, pid(), integer(), integer() | nil -> term()) | atom

    Callback when the spawned process exited.

    Defaults to nil.

    When passing a function, the function should expect 4 arguments,

    1. ExPTY: The module name of ExPTY. This will probably be removed in the first release.
    2. pid(): The genserver pid so that you can reuse the same function for different processes spawned.
    3. integer(): The exit code the spawned process.
    4. integer() | nil: On unix, this is the signal code from the spawned process. On Windows, this value is nil.

    When passing a module name, the module should export an on_data/3 function, this function should expect the same arguments as mentioned above.

    The return value of this callback function is ignored.

Unix-specific Keyword Parameters
  • encoding: String.t()

    Defaults to utf-8. This keyword parameter will probably be removed in the first release.

  • handle_flow_control: boolean()

    Defaults to false.

    Toggle flow control.

  • flow_control_pause: binary()

    Default messages to indicate PAUSE for automatic flow control.

    Customisble to avoid conflicts with rebound XON/XOFF control codes (such as on-my-zsh),

    Defaults to , i.e, XOFF.

  • flow_control_resume: binary()

    Default messages to indicate RESUME for automatic flow control.

    Customisble to avoid conflicts with rebound XON/XOFF control codes (such as on-my-zsh),

    Defaults to , i.e, XON.

Windows-specific Keyword Parameters
  • debug: boolean()

    Defaults to false. This keyword parameter is not used when the backend is conpty, i.e., when Windows version >= 1809.

  • pipe_name: String.t()

    Prefix of the pipe name.

    Defaults to "pipe".

  • inherit_cursor: boolean()

    Whether to use PSEUDOCONSOLE_INHERIT_CURSOR in conpty.

    See docs on createpseudoconsole.

    Defaults to false.

@spec write(pid(), binary()) :: :ok | {:error, String.t()} | {:partial, integer()}

Write data to the pseudoterminal.