Libtmux_unix.Client
An explicit generation-bound connection. Applications retain ownership of the endpoint choice and resource lifetime.
Source and package
- Qualified name
-
Libtmux_unix. Client - Declared in
Libtmux_unix- Package
- libtmux-unix
- Source
- unix/libtmux_unix.mli
- module Client
-
Public owner:
Libtmux_unix
Members60#
Collections and queries1#
- capture function Acquire a complete graph over a recorded interval, with a fixed number of listing commands. Races fail validation. Access to returned values performs no I/O, including after closing the client.
Common operations43#
- t typealias
- capture_text function Capture ordinary rendered screen rows, inclusively, via an owned paste buffer and private file. Reject applicable capture/save hooks. The scratch directory defaults to
/tmpand must be local storage shared with the daemon. Pending and alternate-screen byte modes are unsupported. This observes an interval and establishes no stream continuity barrier. - send_keys function Send named tmux keys in order, without an implicit Enter. Use
send_textfor literal bytes rather than key interpretation. - create_session function Create a detached session on the bound daemon. Name collisions fail.
- create_window function Create detached, rejecting an occupied explicit index.
- split_pane function Create a detached pane beside the target and return the IDs reported by tmux. Omitted
sizelets tmux choose the split; tmux rejects splits when no space remains. - select_layout function Apply a preset or validated custom layout to the window. Pane geometry follows tmux layout rules; capture again to observe the result.
- kill_session function Remove the session and its window links. Windows with no other links and their panes are destroyed. Removing the last session may stop tmux.
- kill_window function Destroy the window, all its session links and every contained pane. This acts on the global window, not a single contextual link.
- kill_pane function Destroy the target pane and its running process. tmux removes a window that becomes empty and may remove its now-empty sessions.
- rename_session function Set the session name, rejecting a conflicting existing name. Bound IDs remain usable; existing snapshots retain their captured names.
- rename_window function Set the global window name. Every session link observes the new name on its next capture; existing snapshots retain the old value.
- link_window function Add a session-specific link to the global window at
index, rejecting an occupied index. The source window and its panes stay shared. - respawn_pane function Start the supplied command in the existing pane. A running process causes failure unless
kill_running:trueexplicitly replaces it. The pane ID remains unchanged. - unlink_window_at function Without
allow_kill, tmux rejects removal of the last link to a window. - select_window_at function Operate on the session's current index at execution, not an old link incarnation.
- select_pane function Make the pane active in its containing window. This does not open or attach a terminal client.
- resize_pane function Request positive cell dimensions, supplying at least one dimension. Omit either dimension to retain it. tmux can constrain the result to the available layout. Capture again to observe the actual dimensions.
- capture_hooks function Capture locally configured built-in hooks. Command values are tmux's printed representation, retained as data.
- move_window_at function Move the source session's current link at
from_index. Destination collisions fail. - break_pane function Move the pane into a new window at an explicit session index. An occupied destination fails. The returned IDs describe the resulting context; the pane itself already existed.
- set_pane_title function Set the pane title as literal text, without tmux format expansion. A running terminal application can subsequently replace the title.
- swap_panes function Exchange pane positions without exchanging their identities or running processes. Both targets must belong to the same bound generation.
- clear_history function Clear stored scrollback for this pane. The visible screen and running process remain; later captures cannot recover discarded history.
- capture_options function Acquire one bounded option table, excluding hooks. The default includes only local entries. Inherited table enumeration includes built-ins; inherited user options require
read_optionwith their explicit name. Built-in descriptors cover every supported release from tmux 3.3a through 3.8; other versions returnLibtmux.Error.Unsupported. - resize_window function Request positive cell dimensions, supplying at least one dimension. Omit either dimension to retain it. Client-size and window-size policies can affect subsequent sizing.
- move_pane function Move the source pane beside another pane, optionally setting the split size. Both targets must belong to the same bound generation. An emptied source window is removed by tmux.
- rotate_panes function Rotate pane positions in the selected direction. Pane identities and running processes remain attached to their panes.
- set_option function Validate the scope and scalar kind before admission. Array values require an index, or
append:true. Without an index, tmux splits appended text using the option's separator and fills the lowest unused indexes. Text is literal; tmux format expansion is disabled. Hooks use a separate operation. - unset_option function Remove a local override or one array element. Global built-ins reset to their tmux defaults; this does not recursively unset child overrides.
- set_hook function Set a hook to a nonempty command list. Without an index, replace the whole hook array, or fill the lowest free index when appending. An explicit
@namecustom hook stores command text as a user option; it requires complete replacement and has no array indexes.read_hookreturns itsLibtmux.Options.Textvalue; bulk hook capture includes built-ins. Commands may cause arbitrary tmux effects when triggered. Hooks that print output are outside the supported control transport contract. - capture_environment function Acquire a bounded table through a read-only command process. Its response must identify the bound daemon while the original pidfd remains live. Unsupported external variable names fail decoding; they are not omitted.
- set_environment function Set a local environment value for future pane processes.
hiddendefaults to false; hidden values remain internal to tmux. Existing processes keep their environment. - unset_environment function Remove the local entry, allowing a global value to apply to future panes.
- wait_for function Wait on a named tmux semaphore using a dedicated bound lane.
- read_option function Read one exact name, including user-option inheritance.
Nonemeans no entry under the selected policy. An invalid target remains an error. The default follows inheritance; this does not identify the defining parent scope. - remove_hook function Remove the local hook or one indexed array entry. An inherited hook may become effective again; this does not stop work it already started.
- version function Read the bound daemon's observed version without I/O.
- remove_environment function Store a removal marker, excluding the variable from future panes.
- request_detach_client_at function Request detachment of the client currently bearing this name. Success confirms request processing, not peer exit. Detaching the library's own primary lane can lose the response and retire its generation.
- refresh_client_at function Request a redraw; no terminal-rendering completion is implied.
- switch_client_at function Switch the client currently bearing this name to the bound session. Environment updates are disabled by default. This can move either a terminal client or a control client; it does not open a new terminal.
- send_text function Literal bytes, without an implicit Enter. NUL is rejected at admission.
Other members16#
- await function Pump admitted work until this operation is finished. Only one blocking caller may own the client at a time. Cancellation removes queued work or drains admitted work before raising
Cancellation.Cancelled. The handle retains its outcome. Draining has at most one exchange timeout from detection; local scratch filesystem I/O and owned-child cleanup must also finish. Each owned child gets 200 ms of TERM grace before forced termination and reaping; scheduling and kernel completion can add time. No background scheduler or worker is started. - cleanup function Read the report supplied at connection time, or its fresh default.
Cleanup.inspectremains available after close. - clear_option_array function Set a local empty array, masking inheritance.
- close function Close owned control clients and descriptors on the owning domain. Later calls retain the original cleanup result, including failure. Each owned helper gets 200 ms of TERM grace, followed by KILL if needed and reaping. This is not a whole-client deadline or a bound on uninterruptible kernel work. No signal targets the daemon. tmux's
exit-unattachedandexit-emptypolicies can end the daemon after its clients or sessions disappear. - connect function Attach to an existing local daemon with at least one session. The caller and daemon must share the PID namespace and filesystem. A local socket pathname alone does not establish these preconditions.
timeoutis the maximum seconds per control exchange, defaulting to one second. Requires Linux pidfd support. The client belongs to the current domain. Initial and auxiliary attachments suppress tmux'supdate-environmentbehavior. - cycle_layout function Select the next or previous tmux preset layout for this window.
- read_hook function Read an exact hook name. Inheritance is included by default;
Nonemeans no entry under the selected policy. Missing targets remain errors. - resize_control_client_at function Set a control client's reported size. tmux rejects terminal clients.
- run function Submit and await. Use the two calls separately to retain an operation handle.
- run_hook function Run the effective hook in an explicit session, window or pane context. A successful result follows completion of its synchronous command queue. Background work started by a hook has its own lifetime. A later hook failure returns an uncertain outcome; preceding effects remain. Named
@hooks returnUnsupportedbecause tmux can hide their parse failures in the server log. Configuration and inspection remain available. - signal function Signal a named tmux semaphore, releasing a waiter or retaining the signal for a later
wait_for. This does not signal an OS process. - source function Read the retained endpoint, daemon PID and connection generation without I/O.
- submit function Validate and reserve queue capacity without I/O.
- subscribe function Acquire verified coverage of the pane's observed session/window. Choose the least session ID unless explicitly supplied. Reuse one lane per session. Defaults: 1 MiB and 1024 queued events per subscriber; at most 16 subscribers and eight client lanes including commands. Reserve payload against the shared 32 MiB budget before admission.
- wait_for_text function Subscribe, capture the ordinary screen immediately, and recapture after output. Membership/overflow gaps trigger explicit fresh capture and new coverage in the same binding. Maximum pattern: 64 KiB. Success returns a capture that contains the text. Transient text between captures may be missed. Check the deadline between bounded acquisitions; in-flight I/O retains the client's exchange timeout. Release the temporary subscription without replacing an earlier error or cancellation; inspect
cleanupfor secondary failures. Otherwise cleanup failure prevents success or renewed coverage. No capture/stream barrier exists. - zoom_pane function Toggle the window's zoom state around this pane.
Guides#
Pages that discuss Client.