Server

Description#

A server is bound to one tmux executable and one Unix socket. It keeps a private link to the socket it bound, so commands never reach a different daemon that later takes over the same path. An EntityRef is valid only on the server that issued it; another server raises TargetNotFoundError.

Methods that run a tmux command take timeout: and cancel:. The typed methods raise CommandError when tmux rejects a command, and a listing that fails raises, so an empty array means tmux answered with nothing to list. #run and #run_group answer their result whatever tmux's exit status. max_requests: bounds concurrent commands and max_controls: bounds control connections; a call past either limit raises CapacityError instead of waiting. After #close the server refuses new requests with ClosedError, and #diagnostics still answers. A forked child can close an inherited server but cannot use it.

What is on here

The methods fall into the groups below. A Session, Window, or Pane carries the operations on that one thing.

Connecting

Binding an endpoint that already exists takes the constructor or the open class method, and open with a block closes the server when the block ends. Given no endpoint:, socket_path: or socket_name:, both bind the socket Endpoint.new picks from LIBTMUX_SOCKET_PATH, LIBTMUX_SOCKET, TMUX and tmux's default socket, in that order. Starting a private daemon instead creates no session, and the started server owns the daemon's exit. A server answers its Endpoint and whether it started its daemon, and reports the request and control slots in use, and the limits. Closing retires the server's clients; on an owned server it also stops the daemon. Open a ControlConnection to a session.

Bind an endpoint

• new
• open

Start a private daemon

• start

Read the endpoint

• endpoint

Ask whether it started the daemon

• owned?

Slots in use and the limits

• diagnostics

Retire the clients

• close

Open a control connection

• open_control

Finding one thing

Each lookup wraps an EntityRef in a handle without running a command. Take the ref from a handle or a snapshot record. A ref of the wrong kind raises TargetNotFoundError; one whose entity has gone fails at its first command.

Handles

• session
• window
• pane
• window_link

Listing everything

Listing sessions, windows, or panes answers frozen arrays of handles in numeric ID order, and listing window links answers every WindowLink. Listing clients answers one hash per client. Taking a snapshot captures the session, window, and pane tree, and clients with clients: true, as one validated Snapshot.

Handles

• list_sessions
• list_windows
• list_panes

Window links

• list_window_links

Clients

• list_clients

One snapshot

• snapshot

Querying things and getting around

A pane search filters the panes of a snapshot with where:, a hash of criteria or a FilterExpr, and answers a Selection; explaining a search answers the plan for a query without running tmux. A Selection narrows, tests whether anything matches, and takes a single match, raising NoMatchError or MultipleMatchesError otherwise, or takes one or nil. Build and compose criteria with FilterExpr. A Snapshot answers relational questions without another command. Its records follow relations by name: a SessionSnapshot reaches windows, panes, and current_window, a WindowSnapshot reaches panes and active_pane, and a PaneSnapshot reaches its window. A handle reads back as a record, and a record turns into a handle through its ref and the server's lookups. Live handles go down one command at a time and back up through the server.

Search the panes of a snapshot

• search_panes

Explain a search without running tmux

• explain_panes

Narrow

• Selection#where
• Selection#select
• Selection#filter
• Selection#reject

Test

• Selection#exists?

Take one

• Selection#one

Take one or nil

• Selection#one_or_nil

Build criteria

• FilterExpr.build
• FilterExpr.from_json

Compose criteria

• FilterExpr#and
• FilterExpr#or
• FilterExpr#not

Read a snapshot's records

• Snapshot#sessions
• Snapshot#windows
• Snapshot#panes
• Snapshot#clients

Read a handle back as a record

• Entity#snapshot

Turn a record into a handle

• CapturedRecord#ref
• session
• window
• pane

Down

• Session#list_windows
• Session#list_panes
• Window#list_panes

Up

• Entity#server

Changing things

Creating a session starts it detached, running command:, an argv array rather than a shell string, and answers the Session or, with receipt: true, a CreationReceipt. Kill stops the tmux server, which closing does only for an owned server. Switching a client points the client named by client: at a session.

Create a session

• new_session

Stop the tmux server

• kill

Point a client at a session

• switch_client

Options and hooks

Ask for Options at server scope, or at the global session or window scope, and for Hooks at the global session or window scope. Read, set, and unset one variable in the server's global environment.

Options

• options

Hooks

• hooks

Read a variable

• environment

Set a variable

• set_environment

Unset a variable

• unset_environment

Everything else tmux keeps

List, read, write, and delete paste buffers. Load a configuration file. Display expands a tmux format; the argument is a format, not literal text. Wait on, signal, lock, or unlock a channel, as action: says.

Paste buffers

• list_buffers
• read_buffer
• write_buffer
• delete_buffer

Load a configuration file

• source_file

Expand a format

• display

Wait on a channel

• wait_for

Things that need a terminal

Attaching runs an interactive client on a TTY the caller supplies and keeps, blocks until that client exits, and answers a TerminalResult. Cancelling detaches the client and does not stop pane commands.

Attach a client

• attach

Running a command

Anything else tmux can do is reachable by running one command, which takes an argv array and keeps tmux's separators and format semantics, or by running several in one tmux invocation. A GroupResult cannot attribute the client's final status to a single step.

Run one command

• run

Run several in one invocation

• run_group