# tmux_control

- **Package:** libtmux_erlang
- **Language:** Erlang
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-erlang/blob/d1b6308440cf9eb8f6647e7ae434bce60e849368/apps/libtmux_erlang/src/tmux_control.erl#L1
- **Page:** https://libtmux.org/en/erlang/latest/reference/tmux_control/

Own an explicit persistent tmux control attachment.

`attach/3` attaches to an existing session from `m:tmux_server` and verifies
the daemon identity on that connection. The caller owns its lifetime.
Attachment changes the session's attached-client count. The command client
uses no-output and ignore-size; -E skips attachment's environment update.
The library issues no session-option writes or session-creation commands.
Configured hooks and native lifetime policies can still change state,
including on failed attach or detachment. Those effects are not rolled back.
Command submission and terminal streaming are not yet exposed.

Use `close/1` before closing the parent endpoint. Parent closing, invalidation
or caller death requests retirement, but parent close alone does not prove
this client's exit. Control close and `status/1` report its native cleanup.
Neither detachment nor cancellation reverses remote effects. Application
shutdown alone is not a verified cleanup result.

## Members

### Common operations

- [`close/1`](/en/erlang/latest/reference/tmux_control-close-1/) (function): Retire this control client and its helper without issuing session or daemon destruction commands. Native lifetime policies and detachment hooks may still change state; cleanup does not reverse their effects. Returns ok only after actual retirement. A finite cleanup failure leaves a supervised owner for retry and observation. Successful close is idempotent during the 60-second handle retention period.

### Other members

- [`attach_options/0`](/en/erlang/latest/reference/t-tmux_control-attach_options-0/) (typealias): Finite attachment budget, including parent registration, exec and identity. Defaults to 2500 ms.
- [`attach/3`](/en/erlang/latest/reference/tmux_control-attach-3/) (function): Attach to an existing captured session from this exact endpoint origin. Performs I/O and waits for a same-connection identity probe. Uses attach-session with -E rather than creating a session or writing options. Configured hooks may change state; failure does not reverse their effects. The control client affects attached_count. Unexpected hook-generated reply blocks fail attachment and retire the client.
- [`state/0`](/en/erlang/latest/reference/t-tmux_control-state-0/) (typealias): Connection state, separate from command completion. complete proves native client/helper retirement; pending and incomplete do not. Retained PIDs are diagnostic observations, never permission to signal a process.
- [`status/1`](/en/erlang/latest/reference/tmux_control-status-1/) (function): Read retained connection state without a tmux command. Inspect cleanup rather than inferring native exit from the Erlang owner's lifecycle. Closed handles expire after 60 seconds and then return control_expired.
- [`t/0`](/en/erlang/latest/reference/t-tmux_control-t-0/) (typealias): A generation-bound connection handle. Passing it does not transfer lifetime ownership.