tmux_session
Create and observe sessions, or act on a session's registered stable ID.
Source and package
- Qualified name
-
tmux_session - Package
- libtmux_erlang
- Source
- apps/libtmux_erlang/src/tmux_session.erl
- tmux_session
-
Description#
create/2accepts name, window_name, width, height, cwd, env, launch and detach. Creation defaults to detached with tmux's configured shell/command. launch is default_shell, an argv map, or an explicit shell map. env augments tmux's inherited environment. tmux supplies PATH, SHELL, PWD and TMUX_PANE after that merge, so those entries may be replaced. Names and cwd are literal format values; tmux's stored name rules still apply. Creation never adopts an existing session by name.An empty shell command can exit immediately and remove its session. It does not request the empty-pane behavior of split-window. Use a running program when later operations require the session to remain alive.
create/2andget/2explicitly read the new/current row through several one-shot commands. These reads are not atomic. If creation succeeds but observation fails, the error retains mutation = completed and the original command result.rename/2andkill/1return command results without refreshing the input record. Detached rows requiretmux_server:bind/2before actions.rename_command/2builds a reusable value without tmux I/O; the other calls perform I/O after validation.select/2switches one explicitly named attached client to a session. It never attaches a client or infers the current client. Usetmux_window_link:select/1to select a session's window membership instead.
Members9#
Common operations7#
- create/2 function Create a detached session by default and explicitly observe the returned row. Options include name, window_name, dimensions, cwd, env and launch. Performs I/O; an observation failure after successful creation retains mutation = completed and the original command result. Existing names are not adopted.
- kill/1 function Destroy this registered session. Performs I/O and returns the command result; this is a destructive session action, not endpoint cleanup. References must belong to a live registered owner.
- rename/2 function Rename the registered session using a literal name and return the command result. Performs I/O. Previously captured records keep their old names; detached or stale references fail validation before the action.
- get/2 function Read fresh session fields through explicit one-shot commands. The session ID is stable within the observed server incarnation. Returns target_gone when tmux no longer has that session; it never refreshes an existing record.
- select/2 function Switch an explicitly named attached client to this registered session, preserving the session environment. Performs I/O. See
select/3for client lookup, environment updates and disconnection races. - select/3 function Switch one attached client, selected by its literal native client name or TTY path, to the session's registered stable ID. Performs I/O and returns the command result; existing rows remain captured values. Obtain the name from the caller's own client context, such as tmux's
client_nameformat. There is no default client and this call never attaches one. - rename_command/2 function Build a literal rename command without tmux I/O. Validates the row and keeps its captured origin; endpoint liveness is checked during execution. Submit the value to
tmux_server:command/3ortmux_operation:start/3with its original endpoint. Existing session records retain their captured name.
Other members2#
- create_options/0 typealias Session creation options. Launch defaults to the configured shell; creation defaults to detached.
- select_options/0 typealias Session selection options. update_environment defaults to false, preserving the destination environment.
Guides#
Pages that discuss tmux_session.