# libtmux.control

- **Package:** libtmux/control
- **Language:** Common Lisp
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-lisp/blob/c2e5fc4ed3befda21f45dfa5d5868c38fd138311/src/control.lisp#L1
- **Page:** https://libtmux.org/en/lisp/latest/reference/libtmux-control/

Persistent native tmux commands and bounded byte events.
Load the optional LIBTMUX/CONTROL system. The qualified backend requires the
core SBCL/Linux profile and an actual tmux daemon >=3.8. Connections own a
worker and process independently of their originating LIBTMUX:CLIENT.
Submission is nonblocking; waits use condition notifications. One worker
serializes requests and reads all protocol data. No application callback
runs in that worker. Commands use tmux argv, not shell source.
Results and events own their mutable bytes and containers. A completed
command queue does not establish application readiness. No automatic replay
or reconnect occurs. Explicit RECONNECT renews the original core client's
generation and returns fresh observations.
See also: WITH-CONNECTION, WITH-RECONNECTION, SUBMIT-COMMAND, NEXT-EVENT.

## Members

### Common operations

- [`await-request`](/en/lisp/latest/reference/libtmux-control-await-request/) (function): Wait for owned result/:READY, or return NIL/:TIMEOUT without cancelling.
TIMEOUT is nonnegative real seconds or NIL for an unbounded wait. Zero polls.
The result plist contains :STATUS, :OUTPUT bytes, :WIRE-TAIL bytes,
:TRUNCATED-P, :EFFECT, :DISPATCHED-P, :REASON and :REPLY-COUNT. Wire tail is
unterminated protocol data, not decoded output. Positive stdin progress makes
DISPATCHED-P true conservatively, even for an incomplete line. A dispatched
failed/cancelled/timed-out/closed request may have effects; never infer rollback.
COMPLETED means the command queue reached its marker, not application readiness.
Only framed replies enter OUTPUT; unframed lines remain notification events.
Repeated awaits return fresh byte storage. No exception hides a terminal result.
- [`next-event`](/en/lisp/latest/reference/libtmux-control-next-event/) (function): Wait for an owned event/:READY or NIL/:TIMEOUT on this connection.
TIMEOUT is nonnegative real seconds or NIL; zero polls. :OUTPUT has :PANE,
:AGE, :EXTENDED-P and :DATA octets, preserving invalid UTF-8. :NOTIFICATION
contains a raw line without LF in :DATA, preserving unknown labels and bytes.
Native %exit is a notification; transport end is reported independently.
Unsolicited :REPLY also has :FAILED-P.
:GAP reports :EVENTS and :BYTES dropped from the bounded queue. An oversized
new event reports loss without discarding retained smaller events.
Local loss does not pause tmux. Native pause/continue notices remain raw
notifications and are distinct from local :GAP delivery.
:END follows retained events, with :REASON, :EXIT-CODE, :DIAGNOSTICS bytes,
:WIRE-TAIL bytes and :CAUSE. After end, repeated reads return end immediately.
Causes retain condition identity. No application callback executes in the reader.
- [`submit-command`](/en/lisp/latest/reference/libtmux-control-submit-command/) (function): Queue copied tmux ARGV and return a REQUEST without waiting for its reply.
EFFECT must explicitly be :READ or :MUTATION; it records caller intent, not a
command restriction. TIMEOUT is a nonnegative real deadline budget starting at
submission, including queue time. A zero budget can expire before dispatch.
Commands execute serially. Full queues signal CONNECTION-BUSY; closing ones
signal CONNECTION-CLOSED. Use argv for tmux syntax, not shell interpolation.
This raw path does not validate or refresh captured operational targets.

### Other members

- [`cancel-request`](/en/lisp/latest/reference/libtmux-control-cancel-request/) (function): Request cancellation; return true only when this call changes live work.
Queued work is removed without dispatch or connection closure. Active work
closes its connection and retires unissued queued requests. The worker records
write progress before publishing :CANCELLED; await it to inspect that evidence.
Cancellation winning before completion preserves :CANCELLED; an already terminal
request is unchanged. No command is replayed and dispatched effects are not undone.
- [`close-connection`](/en/lisp/latest/reference/libtmux-control-close-connection/) (function): Close this connection's worker and process; return NIL after cleanup.
Leave the tmux daemon running. Concurrent closes serialize; repeated successful
close is harmless. In-flight results retain partial output and dispatch state.
Cleanup can add time beyond request deadlines. Failure signals
CONNECTION-CLEANUP-FAILED and retains this resource for explicit retry.
- [`connection`](/en/lisp/latest/reference/libtmux-control-connection/) (class): An owned persistent tmux connection with one protocol worker.
Use WITH-CONNECTION or CLOSE-CONNECTION to release it. Closing the originating
core client does not close this resource. Captured core observations remain
separate; raw control commands do not refresh them. RECONNECT requires that
original core client to remain open.
- [`connection-busy`](/en/lisp/latest/reference/libtmux-control-connection-busy/) (exception): The bounded request queue, including active work, is full.
Submission did not dispatch this command. See also: SUBMIT-COMMAND.
- [`connection-cleanup-failed`](/en/lisp/latest/reference/libtmux-control-connection-cleanup-failed/) (exception): Closing failed; retry CLOSE-CONNECTION on ERROR-CONNECTION.
The resource remains discoverable through PENDING-CLEANUPS. No mutation is
replayed. See also: CONNECTION-CLEANUP-FAILURES, LIBTMUX:ERROR-CAUSE.
- [`connection-cleanup-failures`](/en/lisp/latest/reference/libtmux-control-connection-cleanup-failures/) (function): Return a fresh vector of the last 16 close failures, newest first. No I/O.
Condition objects are retained by identity. WITH-CONNECTION records secondary
cleanup failures while preserving an existing body error or nonlocal exit.
- [`connection-closed`](/en/lisp/latest/reference/libtmux-control-connection-closed/) (exception): Submission attempted on a closing or closed connection.
- [`connection-error`](/en/lisp/latest/reference/libtmux-control-connection-error/) (exception): A control failure retaining its connection and original cause.
- [`connection-failure`](/en/lisp/latest/reference/libtmux-control-connection-failure/) (function): Return the retained worker failure condition, or NIL, without I/O.
Conditions retain identity; byte data comes from NEXT-EVENT or AWAIT-REQUEST.
- [`connection-stale`](/en/lisp/latest/reference/libtmux-control-connection-stale/) (exception): The original control client generation, daemon or session changed.
ERROR-CONNECTION and LIBTMUX:ERROR-TARGET retain the old public connection.
Acquire fresh observations and use OPEN-CONNECTION explicitly; stale authority
cannot authorize reconnection to a replacement target. No request is replayed.
- [`connection-start-failed`](/en/lisp/latest/reference/libtmux-control-connection-start-failed/) (exception): Startup failed after allocating a connection resource.
ERROR-CONNECTION retains the resource even if cleanup also failed. Core
argument and unsupported-capability errors before allocation stay core types.
- [`connection-state`](/en/lisp/latest/reference/libtmux-control-connection-state/) (function): Return :STARTING, :READY, :CLOSING or :CLOSED without I/O.
This is an observation, not a lease for subsequent submission.
- [`error-connection`](/en/lisp/latest/reference/libtmux-control-error-connection/) (function): Return the retained connection implicated in a CONNECTION-ERROR. No I/O.
- [`open-connection`](/en/lisp/latest/reference/libtmux-control-open-connection/) (function): Attach a separate owned control connection to a captured SESSION.
CLIENT supplies the core endpoint and authority. Startup preflights the target
and requires the live daemon to be >=3.8. TIMEOUT bounds startup admission and
supervised execution; platform preparation and cleanup add caller wall time.
REQUEST-LIMIT includes active and queued work. Events drop oldest entries at
EVENT-LIMIT or EVENT-BYTE-LIMIT and report loss. REPLY-BYTE-LIMIT bounds each
request's retained output; overflow closes the connection with a cause.
This call blocks until ready or failed. All limits must be positive integers
except the nonnegative real TIMEOUT. No daemon is started or terminated.
Attachment preserves the stored session environment; native attach hooks and
server lifecycle policies still apply. Readiness checks the observed daemon
witness after attachment, so a refused candidate may have appeared briefly.
- [`pending-cleanups`](/en/lisp/latest/reference/libtmux-control-pending-cleanups/) (function): Return a fresh vector of connections retaining failed cleanup work. No I/O.
Retry CLOSE-CONNECTION explicitly. Successful close removes the entry.
- [`reconnect`](/en/lisp/latest/reference/libtmux-control-reconnect/) (function): Retire CONNECTION and return a fresh connection and complete snapshot.
Use the original core client and exact session ID. The client must remain open
in the original generation. Explicitly supplied limits must be positive integers;
omitted queue/reply limits inherit the old connection. TIMEOUT is nonnegative
real seconds shared across preflight, retirement, recapture and startup;
preparation and cleanup can add wall time. Capture output shares the core
client's output budget. Concurrent core work signals LIBTMUX:CLIENT-BUSY.
Preflight refusal leaves a live old connection alone. After successful close,
renew the core generation even if later work fails. Every earlier core capture
from that client becomes stale for operations, while local data remains usable.
The returned snapshot precedes new attachment; it does not include that new
frontend. A closing/closed old resource remains reconnectable with valid origin.
Old requests/results/events stay on the retired resource. Pending work is closed,
never replayed; dispatched effects can remain uncertain. Other separately owned
control resources remain independent. No event continuity or replay is implied.
The CLOSE-CONNECTION generic runs on the caller thread; its failures are retained.
CONNECTION-STALE refuses changed origin/session/daemon. Old cleanup failures
retain the old resource; startup failures retain the new candidate through
CONNECTION-START-FAILED. After failed cutover, acquire/select and open anew.
Use WITH-RECONNECTION or close the returned resource explicitly.
- [`request`](/en/lisp/latest/reference/libtmux-control-request/) (class): One queued command and its retained dispatch/result evidence.
Keep this handle to await or cancel work. A wait timeout leaves it live.
- [`request-state`](/en/lisp/latest/reference/libtmux-control-request-state/) (function): Return retained request state without I/O.
States are :QUEUED, :WRITING, :RUNNING, :COMPLETED, :FAILED, :TIMED-OUT,
:CANCELLED and :CLOSED. A terminal result is never replaced by cancellation.
- [`with-connection`](/en/lisp/latest/reference/libtmux-control-with-connection/) (function): Bind NAME to a control connection and close the original resource on exit.
Evaluate CLIENT, SESSION and OPEN-CONNECTION options once. BODY accepts
declarations and returns all its values. Rebinding NAME cannot redirect cleanup.
After normal return, propagate cleanup failure; during an error or nonlocal
exit, preserve that exit and record cleanup failure on the connection.
- [`with-reconnection`](/en/lisp/latest/reference/libtmux-control-with-reconnection/) (function): Bind a fresh NAME and SNAPSHOT from explicit RECONNECT; close NAME on exit.
Evaluate PREVIOUS and options once. BODY permits declarations and returns all
values. Rebinding either visible name cannot redirect cleanup. Preserve primary
errors/nonlocal exits and record secondary cleanup errors on the new connection.
The previous resource retains its own old results and events.