API reference

One tmux server, addressed by the socket it listens on.

Which server answered: tmux, a compatible reimplementation, or not yet determined.

Coarse-grained promises callers choose around.

What this server is known to support, decided without asking it.

Reads LIBTMUX_SOCKET_PATH, then LIBTMUX_SOCKET.

-L name: a single component resolved under the socket directory.

-S path: used verbatim, so the address limit applies to it directly.

One session, as one listing saw it.

An entity formats as it prints.

Hashing an entity uses exactly what its equality compares, so values from separate listings key an unordered container consistently.

Distinct types, not aliases of one: Kind is only ever named here.

tmux renders a timestamp as epoch seconds, which is what a filter compares and what -f would compare on the server.

A session target is its id, or its validated name.

One window, as one listing saw it.

Hashing a window, on the same terms as its equality.

A window target is its id, which needs no session, or session:window.

One pane, as one listing saw it.

Hashing a pane, on the same terms as its equality.

A pane that has not exited reads -1, which tmux cannot report: the field is WEXITSTATUS and so is 0 through 255, or empty.

Whether a value is written as an id, which is what decides that it needs no separator validation below — not whether tmux would resolve it.

A pane target is its id, or session:window.pane.

One attached client, as one listing saw it.

Hashing a client, on the same terms as its equality.

One name in the environment tmux gives processes it starts.

One option as tmux reports it: its name, its value, and the array index it sits at when it is an array option.

Parse one line.

Undo the quoting tmux applies when it prints a value.

Named keys tmux accepts, taken from the table in its own key-string.c at the oldest supported release.

Accept a key with any number of C-, M-, or S- modifiers.

Send text exactly as written: the flag, the end of flags, and the text.

A named piece of text the server holds, outliving the pane it came from.

Epoch seconds, as tmux renders it and as -f would compare it; the accessor beside this one answers sys_seconds because that is what a caller holds.

Check names, v1 saved-layout checksum, v1/v2 tree grammar and minimum cell count without I/O.

The socket the environment selects, or none.

A tmux version, ordered so a feature gate can compare against a literal.

The oldest release this library supports: 3.3a.

The floor as the messages name it; parse_version() reads it back as kMinimumSupported.

The same version, available to the preprocessor.

This package's own version, not tmux's.

Parse the first line of tmux -V, with or without its trailing newline.

An attach argv and the private route selecting this server incarnation.

One command this tmux understands.

One argument, carrying whether any part of it is a secret.

The argv a chain becomes: commands joined by tmux's separator.

A transport a caller supplies.

Move-only result handle for one admitted command; its methods are not concurrent.

Move-only owner of the transport threads, admission bound, and observations.

Whether an argument may appear in a diagnostic, a log, or an error message.

Which path answered the wait.

A command that did not produce an answer, and how far it got.

Told about every command, as it finishes.

The maximum number of accepted commands retaining any lifecycle leg.

The first successful close() report; every later call returns this value.

What a call waits and holds when the caller did not say.

Formatting a failure is how it reaches a log line, so the type every call can return knows how to write itself.

Every member expires on return; a caller keeping any of it copies it.

One held-open control client.

Everything tmux says, until the deadline, as one loop.

Single-pass, and the value it yields is borrowed: advancing invalidates the notification the previous dereference viewed.

One independent view of outside-block events emitted after opening.

The control-mode wire format, decoded into whole events.

How tmux closed a reply block: normally, or reporting a failure.

One reply block, framed between tmux's begin and its terminator.

One command as argv, before it is joined into a control-mode line.

One control event tmux sent unprompted, still as bytes.

A notification's arguments, as views into the notification it was read from.

How much of one reply a decoder holds, and how long a single line may grow before the stream is called broken.

Whether pane_id (%N) is still part of a window's arrangement, reading a NotificationKind::layout_change notification's own text — window_layout followed by window_visible_layout and the window's flags (control-notify.c) — for its first, whitespace-delimited token.

Build a format from alternating literal and variable pieces so a caller never hand-concatenates and forgets to escape one of them.

Where a tmux subcommand wants its format string.

A separator absent from every format name is not absent from every format value, which is the whole difficulty.

tmux joins requested formats with a separator that cannot appear in a format name.

Escape literal text for inclusion in a format string.

Wrap a variable name as a substitution.

Several expressions combined, all of them or any of them.

A borrowed element of a range, rather than a copy of it.

The related entity is whatever the accessor yields, so a bare flag field can stand in for a predicate here exactly as it does in matching().

The entity on the far side of a to-one link, with the accessor's indirection and qualifiers stripped away.

Join two listings on the id one of them carries.

exactly_one() states that several is a caller error, and says which one.

A forward range's iterator can be copied and advanced independently of the original, so a second element rules the range out before the first is materialized.

first() states that a caller tolerates extras; it never reports several.

Copies referenced elements; moves when an iterator yields an rvalue.

An absent to-one link never satisfies is(): a window with no active pane is not a window whose active pane runs an editor.

eq is the implicit lookup, matching Python's bare field=value.

A sink receives one call per node in prefix order.

matching(expr) is a range adaptor closure so it composes with std views.

matching(expr) is a range adaptor closure so it composes with std views.

The same join read the other way: the one row a child points at, or none.

Parse one field[__lookup]=value term against a caller-supplied field table.

To-many and to-one links take different accessors, so they get different builders rather than one that has to compile both shapes.

Replay an already-lowered child into a sink.

A flag on an entity, named for the expression and read through a function pointer rather than a member pointer so the same descriptor works for a field computed from several tmux tokens.

The value a flag's name resolves to in an expression.

A numeric field on an entity, read as a number rather than as the text tmux sends, so 9 orders before 10.

The value a numeric field name resolves to in an expression, whose comparison operators build the node rather than comparing anything.

A field is a named accessor: the name is what a future tmux-format lowering needs, the accessor is what in-memory evaluation needs.

A typed field handle.

How a text field is compared. StringOp::iequals folds case; the rest do not.

tmux renders a count, a size and an index as text.

Whether a group's operands must all hold or any one of them.

How a filter applies across a relation.

One expression inverted.

A filter over one entity type, as a value.

One node of a filter after it has been reduced to what tmux's -f format language can express.

A whole lowered filter, flat: children are referenced by index rather than owned, so the vector can be walked without recursion.

Owning row storage, shared by every entity taken from it.

A lock-consistent instant; values may change immediately after it is read.

The lines are views into the text, so text that dies at the semicolon takes them with it — and pane.capture() returns its output by value, which makes capture_lines(*pane.capture()) the natural thing to write and a use-after-free to run.

Undo that escaping, in place.

Build the format argument for one entity's fields, terminating every field so a trailing empty value is still a value rather than a missing column.

Whether wanted appears in captured text as something the pane produced, rather than as text that is merely on screen.

Split one tmux output line into its field values.

Drop the blank rows a pane pads its height with, keeping blank lines that have content below them.

One tmux command as argv, with no shell between it and tmux.

The commands sent as one group, which tmux runs until one fails.

Why a lookup that required exactly one match did not get one.

Why a key name could not be resolved to something tmux accepts.

Why a legacy lookup string could not be read.

Why a socket name or path was rejected before any server was contacted.

Why a target could not be built from a name.

Why a tmux version string could not be read.

Why a control operation stopped.

Which error types name a validation reason rather than a runtime failure.

A control-wire failure as a command failure, keeping what it says about delivery — the one thing a caller cannot reconstruct.

The other direction, for a caller handing a command failure to a surface that speaks the wire's type.

How commands reach the server: by spawning a process, or through a backend the caller supplied.

Why a command did not produce an answer, in the order a caller would diagnose them: bad before it left, then how it left, then what came back.

What a notification is, once its name and arguments have been read.

Which part of a pane's screen and scrollback a capture reads.

How to start a control-mode connection, and what it is allowed to buffer.

What one request produced: its reply blocks, and the connection error that ended the exchange if one did.

What a caller-supplied transport tells the library about itself.

What a creation command can be told.

Anything the parser produces: a reply to something asked, or something tmux said on its own.

What a new session is created as, including its first window.

What a new window is created as, and where it lands.

Environment variables set for the lifetime of this value and restored on destruction, including the ones that were previously unset.

A tmux server that exists for the lifetime of this value.

Whether the test server is addressed by tmux -L name or tmux -S path.

A flag compared against an expected value.

A numeric field compared against a number.

A relation crosses to another entity type, so its child expression cannot live in this variant.

A text field compared against an operand this node owns.

How the test server is started and how long teardown may take.

Names the private tree, the socket and the tmux -L name, so concurrent suites cannot collide and a leftover directory identifies its owner.

What teardown could not clean up, so a suite can fail loudly rather than leave a server behind quietly.

Skip unless tmux is at least the release major.minor, naming what is missing below it.

Skip while tmux is inside a closed range of releases with a known defect.

Build and edit a NAME=VALUE block for a child process.

What tmux -V printed, verbatim, or "unknown".

Whether running ranks below the release major.minor.

Resolved once per distinct binary and cached.

Whether two paths name the same socket.

A value or the reason there is not one.

The error side of expected, named for the rare declaration that has to spell it.

What value() throws when there is none.

Declared so the private constructor has exactly one way in.

tmux renders flag formats as "1" or "0"; anything else is not the flag.

tmux renders every value as text.

A factory rather than an alias: an alias template cannot deduce its argument, so unexpected(error) would stop compiling at every call site.

Several commands built up and sent as one tmux invocation.

A tmux object id, typed by what it names.

Collects a lowered expression.

The storage every entity has, in one place: the snapshot that owns the bytes and which of its rows this entity is.

How far a command is known to have got before something stopped it.

What chose a socket when the caller named none.

Validate one path component.