tmux_buffer (libtmux for Erlang v0.0.1)
View SourceLoad, inspect and paste tmux byte buffers through an explicit endpoint.
Use load/3 for binary payloads, including NUL bytes, and show/2 to read
them back without terminal escaping or an added newline. list/1 returns
captured metadata in tmux's newest-first order; it never loads payloads.
paste/3 sends a named buffer to a registered pane. Direct input is available
through tmux_pane:send_text/2.
Names are NUL-free binaries, distinct from payload bytes. New names retain
tmux's storage rules: 3.7+ cleans names and can reject control bytes or escape
backslashes. Use observed names from list/1 for subsequent calls. Empty load
input is tmux's no-op; it neither creates nor clears a buffer. delete/2
removes a buffer explicitly. Names have no persistent object identity, and
concurrent commands can replace a buffer between calls.
All operations except capabilities/1 perform explicit I/O. They use the
one-shot transport and preserve operational errors and ownership checks.
The buffer guide shows a complete byte round trip.
Summary
Types
Source-defined buffer behavior for a parsed daemon version.
Captured name, payload byte count and Unix creation time; not a live handle.
Paste controls. separator defaults to LF; delete and bracketed default to false. sanitize defaults to false, preserving bytes. Explicit sanitization requires tmux 3.7+. Bracketing occurs only when the pane enables bracketed paste.
Read bounds: max_bytes defaults to 1 MiB; deadline_ms defaults to 2500.
A stored buffer name, or latest to let tmux select its newest buffer.
Functions
Describe version differences without I/O. This does not qualify an untested
release. paste/3 uses paste_sanitize to gate sanitization and render raw paste.
Delete a named buffer or latest. Missing buffers return buffer_not_found. This performs I/O and affects the server-wide buffer store.
Capture metadata in tmux's newest-first insertion order. Renaming preserves
position; replacing data through load/3 inserts a new buffer. Length frames
preserve names containing delimiters, newlines or invalid UTF-8 on releases
that permit them. Returns an ordinary list, bounded to 4096 rows and 1 MiB of
encoded output. No payloads, hidden refresh or atomic snapshot is provided.
Load binary bytes under a name, or create an automatic buffer. Input may
contain NUL. Empty input succeeds without changing the buffer store, including
an existing name. The command payload, including argv and stdin, must fit the
endpoint's 256 KiB admission limit. See tmux_server:command/3.
Send a named buffer or latest to a registered pane. Defaults preserve payload bytes: LF separators and unsanitized input. On tmux 3.7+, raw paste uses -S; sanitize=true selects its safe print encoding. Earlier releases reject that request with unsupported_capability before dispatch.
Rename one explicit name. tmux 3.3 refuses an occupied destination; 3.4+ replaces
it. This is native collision behavior, not an atomic absence check. Identical
input names return same_buffer_name before I/O, avoiding unsafe legacy tmux
paths. New names retain native cleaning rules; see list/1 for stored names.
The same observed 3.3/3.3a missing-name preflight and race as delete/2 apply.
Read exact payload bytes with default bounds. See show/3 for limits.
Read exact payload bytes from an unattached one-shot client. No print decoding or newline removal applies. max_bytes is 0 through 1 MiB; exceeding it returns output_limit with partial command evidence, never a successful truncated value. deadline_ms is 1 through 600000. Missing buffers return buffer_not_found.
Types
-type capabilities() :: #{paste_sanitize := boolean(), cleaned_names := boolean(), rename_replaces := boolean(), strict_named_target := boolean()}.
Source-defined buffer behavior for a parsed daemon version.
-type info() :: #{name := binary(), size := non_neg_integer(), created := non_neg_integer()}.
Captured name, payload byte count and Unix creation time; not a live handle.
-type paste_options() :: #{separator => binary(), delete => boolean(), bracketed => boolean(), sanitize => boolean()}.
Paste controls. separator defaults to LF; delete and bracketed default to false. sanitize defaults to false, preserving bytes. Explicit sanitization requires tmux 3.7+. Bracketing occurs only when the pane enables bracketed paste.
-type read_options() :: #{max_bytes => 0..1048576, deadline_ms => 1..600000}.
Read bounds: max_bytes defaults to 1 MiB; deadline_ms defaults to 2500.
-type target() :: binary() | latest.
A stored buffer name, or latest to let tmux select its newest buffer.
Functions
-spec capabilities(tmux_version:t()) -> capabilities().
Describe version differences without I/O. This does not qualify an untested
release. paste/3 uses paste_sanitize to gate sanitization and render raw paste.
1> {ok, V} = tmux_version:parse(<<"tmux 3.3">>), ok.
ok
2> tmux_buffer:capabilities(V).
#{paste_sanitize => false,cleaned_names => false,
rename_replaces => false,strict_named_target => false}
-spec delete(tmux_server:t(), target()) -> {ok, tmux_operation:completed()} | {error, map()}.
Delete a named buffer or latest. Missing buffers return buffer_not_found. This performs I/O and affects the server-wide buffer store.
On 3.3/3.3a, named deletion first checks existence with a zero-output show/3
read because native deletion falls back to the newest buffer when a name is
absent. This check does not collect a payload or depend on the list bounds.
It is not atomic: concurrent removal after the check can trigger that fallback.
Use external serialization or tmux 3.4+ when that race is unacceptable.
-spec list(tmux_server:t()) -> {ok, [info()]} | {error, map()}.
Capture metadata in tmux's newest-first insertion order. Renaming preserves
position; replacing data through load/3 inserts a new buffer. Length frames
preserve names containing delimiters, newlines or invalid UTF-8 on releases
that permit them. Returns an ordinary list, bounded to 4096 rows and 1 MiB of
encoded output. No payloads, hidden refresh or atomic snapshot is provided.
-spec load(tmux_server:t(), binary() | automatic, binary()) -> {ok, tmux_operation:completed()} | {error, map()}.
Load binary bytes under a name, or create an automatic buffer. Input may
contain NUL. Empty input succeeds without changing the buffer store, including
an existing name. The command payload, including argv and stdin, must fit the
endpoint's 256 KiB admission limit. See tmux_server:command/3.
Returns the completed command result, not a persistent buffer handle. No clipboard write is requested. Native stored-name rules still apply.
-spec paste(tmux_model:pane(), target(), paste_options()) -> {ok, tmux_operation:completed()} | {error, map()}.
Send a named buffer or latest to a registered pane. Defaults preserve payload bytes: LF separators and unsanitized input. On tmux 3.7+, raw paste uses -S; sanitize=true selects its safe print encoding. Earlier releases reject that request with unsupported_capability before dispatch.
separator is NUL-free; delete removes the buffer after the native paste call. bracketed adds markers only if the target has enabled that terminal mode. Native input-off/dead-pane behavior still applies. Completion establishes the tmux command result, not consumption by the child. No automatic retry occurs.
-spec rename(tmux_server:t(), binary(), binary()) -> {ok, tmux_operation:completed()} | {error, map()}.
Rename one explicit name. tmux 3.3 refuses an occupied destination; 3.4+ replaces
it. This is native collision behavior, not an atomic absence check. Identical
input names return same_buffer_name before I/O, avoiding unsafe legacy tmux
paths. New names retain native cleaning rules; see list/1 for stored names.
The same observed 3.3/3.3a missing-name preflight and race as delete/2 apply.
-spec show(tmux_server:t(), target()) -> {ok, binary()} | {error, map()}.
Read exact payload bytes with default bounds. See show/3 for limits.
-spec show(tmux_server:t(), target(), read_options()) -> {ok, binary()} | {error, map()}.
Read exact payload bytes from an unattached one-shot client. No print decoding or newline removal applies. max_bytes is 0 through 1 MiB; exceeding it returns output_limit with partial command evidence, never a successful truncated value. deadline_ms is 1 through 600000. Missing buffers return buffer_not_found.