tmux.Server

struct tmux.Server

struct [source] ¶

struct [source] ¶

struct tmux.Server

Server is an immutable handle to one tmux configuration. Its zero value is invalid. Copying a configured Server preserves its configuration and shares version-cache coordination; only the documented concurrent operations are safe to share.

Members

• AppendOption method AppendOption appends to a server-scope option without refreshing existing models. Completed failures are secret-safe option errors; cancellation does not prove the append was not accepted.
• AttachSession method AttachSession attaches the caller's terminal to a matching session and blocks until detach or context cancellation. Nil standard streams inherit the process streams; each stream must be a concrete terminal descriptor. The call retains caller-supplied files while attached and never owns or closes them. A completed nonzero exit returns CommandError ; cancellation can end waiting but does not prove that attachment or detachment did not occur.
• BindKey method BindKey binds Key to Command in a tmux key table. An empty Command creates a no-op binding on tmux 3.3 or newer; tmux 3.2a reports its upstream error. It mutates the table; cancellation does not prove that tmux did not bind Key.
• ClearPromptHistory method ClearPromptHistory clears all tmux prompt history or one selected class. Version, transport, and completed-stderr failures are returned. It requires tmux 3.3 or later and returns VersionTooLowError below that floor.
• Client method Client performs a canonical live lookup of name and returns a new record.
• Clients method Clients materializes attached clients. Failures, including ErrNoServer, remain errors rather than empty results.
• Cmd method Cmd executes raw tmux arguments and returns caller-owned result slices. A completed nonzero exit remains a result; validation and transport failures return errors. Cancellation cannot prove whether a mutation reached tmux.
• CommandPrompt method CommandPrompt asks tmux to display a background command prompt and returns after tmux accepts it, not after input is submitted or Template runs. It requires tmux 3.3. Later flags follow UnsupportedPolicy . Completed stderr is an error; cancellation does not prove prompt delivery or later execution.
• ConfigFile method ConfigFile returns the configured tmux configuration path.
• ConfirmBefore method ConfirmBefore asks tmux to display a background confirmation prompt and returns after tmux accepts it, not after the user answers or Command runs. It requires tmux 3.3. ConfirmKey and DefaultYes require tmux 3.4 and follow UnsupportedPolicy . Completed stderr is an error; cancellation does not prove prompt delivery or later command execution did not occur.
• ConnectionBound method ConnectionBound reports whether this handle retains terminal transport owned by a Connection . A bound handle never reconnects or falls back to a tmux subprocess after that connection closes.
• DeleteBuffer method DeleteBuffer deletes a named buffer, or the most recent buffer when name is nil. Cancellation does not prove that tmux did not delete the buffer.
• DetachAllClients method DetachAllClients detaches every client except KeepClient or tmux's current client. Cancellation does not prove every client was detached.
• DetachClient method DetachClient detaches one client, or tmux's current client when no target is set. A completed stderr result is an error; cancellation does not prove delivery or detachment did not occur.
• DisplayMenu method DisplayMenu displays a menu and waits until tmux closes it. The target client must own a TTY; control-mode clients cannot render menu overlays. It returns no selected value and does not establish whether an item command ran. Unsupported optional flags follow UnsupportedPolicy . Completed stderr is an error, and cancellation does not prove menu delivery or a selected command's effect.
• DisplayMessage method DisplayMessage displays or prints a server-scoped tmux message. Print returns an owned stdout slice even when tmux exits nonzero; completed stderr is delivered synchronously through WarningCommandStderr , not returned as a completed-error classification. Unsupported flags follow UnsupportedPolicy . Any warnings run on the caller goroutine before return. Cancellation does not prove display did not occur.
• Equal method Equal reports whether both handles currently select the same socket path. It evaluates relative paths and environment-dependent named and default sockets against each handle's frozen binding.
• Executable method Executable returns the absolute tmux executable path resolved when the server was constructed. An invalid server returns an empty string.
• GetEnvironment method GetEnvironment returns one non-hidden global environment entry. A missing or hidden variable reports ok false.
• GlobalSessionScope method GlobalSessionScope returns a handle that preserves s and its error policy.
• GlobalWindowScope method GlobalWindowScope returns a handle that preserves s and its error policy.
• HasSession method HasSession reports whether Target selects a session. With Pattern false it compares session names exactly; with Pattern true, tmux may resolve IDs, client TTYs, unique prefixes, or globs. Pattern-mode completed nonzero exits are misses. Exact-name lookup treats ErrNoServer as a miss and returns other failures.
• IfShell method IfShell executes ThenCommand when ShellCommand succeeds and ElseCommand, if present, when it fails. A completed stderr result is an error; cancellation can interrupt delivery without proving that tmux did not execute a branch.
• IsAlive method IsAlive reports whether a tmux server answers on the configured socket. Only an absent server reports false without an error: a socket that exists but cannot be reached, such as one the process may not read, is a question that could not be answered and is returned as an error.
• Kill method Kill terminates the configured tmux server and all of its sessions, windows, panes, and clients. After a completed failed kill, a liveness probe makes repeated calls harmless when no daemon answers. Transport or context errors can be delivery-ambiguous; no rollback is attempted.
• KillSession method KillSession terminates the session selected by tmux target syntax. Pattern and prefix matching are deliberately left to tmux. Completed nonzero exits without stderr are ignored. Transport and context errors are delivery-ambiguous.
• ListBuffers method ListBuffers returns an owned snapshot of live tmux buffer rows. A command or transport failure is returned rather than answered with no rows; context cancellation still returns its context error. The result is not a live collection.
• ListClients method ListClients returns an owned snapshot of raw tmux client-description lines. A list failure is returned rather than answered with no rows.
• ListCommands method ListCommands returns an owned snapshot of raw tmux command-description lines. A list failure is returned rather than answered with no rows. Like Server.ListKeys , it answers on a socket holding no server.
• ListKeys method ListKeys returns an owned snapshot of raw tmux key-binding lines. Format requires tmux 3.7 and follows UnsupportedPolicy . tmux 3.7 through 3.7c send a table's sole matching binding to client status and leave stdout empty; this method preserves that upstream and Python behavior. Listing failures remain errors.
• LoadBuffer method LoadBuffer reads a file into a named or newly allocated buffer. Path follows Server.SourceFile 's current-user expansion and lexical normalization. It mutates tmux's destination buffer and rejects exact "-" because no process stdio is exposed.
• LockClient method LockClient locks a client, or tmux's current client when targetClient is nil. Cancellation does not prove the target client was not locked.
• LockServer method LockServer locks every attached client on the tmux server. Cancellation does not prove the server did not lock a client.
• NewSession method NewSession creates a detached session, then returns a newly materialized Session . It never changes client focus. KillExisting is not rolled back; transport and context failures may be delivery-ambiguous.
• NewSessionConnection method NewSessionConnection creates a session with a control-mode client and keeps that same process as the first terminal command lane. Unlike Server.NewSession , it creates an attached session. If tmux reports a valid session ID before later setup fails, the returned partial session retains that ID and server. Cleanup closes the attached creator, so tmux policy may make the partial session no longer live. Before tmux 3.6, destroying the created session follows its detach-on-destroy policy and may end the connection. KillExisting is rejected because removing an existing session cannot be rolled back if later connection setup fails.
• OpenControl method OpenControl starts a control-mode client attached to session. The startup context bounds process start, attach framing, and client registration but does not own the returned client's lifetime. Session must belong to the same configured server selector.
• OpenNotifications method OpenNotifications starts an owned observation-only stream attached to session. Session must belong to the same configured server selector. A connection-bound server returns ErrConnectionRequiresProcess.
• Options method Options returns a freshly decoded, caller-owned view of known server options, including inherited values. A read or transport failure is returned rather than answered with zero values; context errors propagate. Each returned accessor names the setter that writes it, so ServerOptionValues.BufferLimit pairs with Server.SetBufferLimit .
• Pane method Pane performs a canonical live lookup of id using tmux's canonical session and returns a newly materialized record. It does not preserve a linked-session view; use Pane.ResolveWindow for that exact relationship.
• Panes method Panes materializes pane records for every winlink. Failures, including ErrNoServer, remain errors rather than empty results.
• ProcessEnvironment method ProcessEnvironment returns the normalized environment explicitly supplied through ServerOptions . Nil means the server inherited a private process snapshot. The returned slice is owned by the caller; an invalid server returns nil.
• RaiseIfDead method RaiseIfDead returns a CommandError when the configured server is not alive. Cancellation and transport failures are returned directly.
• RawOption method RawOption returns one exact server-scope option value. A successful string is caller-owned; ok reports presence. Targeted reads do not use list leniency, and completed failures return a secret-safe option error. An unindexed empty array is indistinguishable from an empty scalar; use Options for typed array presence.
• RefreshClient method RefreshClient redraws a client, or tmux's current client when no target is set. RequestClipboard requires tmux 3.4 and follows UnsupportedPolicy .
• RefreshVersion method RefreshVersion invalidates the cached version and probes the binary again. Canceling ctx stops this call's wait; it does not establish whether a probe reached the configured binary.
• RemoveEnvironment method RemoveEnvironment marks a variable for removal from new process environments.
• RequireVersion method RequireVersion returns a VersionTooLowError matching ErrVersionTooLow when the configured binary is older than minimum.
• RunShell method RunShell executes a shell command through tmux and returns an owned stdout slice. A background request returns nil after tmux accepts the job. Unsupported optional flags follow UnsupportedPolicy . A completed stderr result is an error; context cancellation can be observed with errors.Is but does not establish that tmux did not start the job.
• SaveBuffer method SaveBuffer writes a named or most-recent buffer to a file. Path follows Server.SourceFile 's current-user expansion and lexical normalization. It changes that file; exact "-" is rejected because the runner exposes no process stdio.
• SearchClients method SearchClients returns a newly materialized snapshot projection of clients selected by tmux's live -f expression. A nil filter omits -f and requests the unfiltered listing on every supported tmux version. A nonnil filter, including an empty expression, requires tmux 3.4 or newer and otherwise returns VersionTooLowError .
• SearchPanes method SearchPanes returns a newly materialized snapshot projection of pane views selected by tmux's live -f expression. A nil filter omits -f and a nonnil empty filter sends an explicit expression.
• SearchSessions method SearchSessions returns a newly materialized snapshot projection of sessions selected by tmux's live -f expression. A nil filter omits -f; a nonnil empty filter remains an explicit empty expression.
• SearchWindows method SearchWindows returns a newly materialized snapshot projection of winlinks selected by tmux's live -f expression. A nil filter omits -f and a nonnil empty filter sends an explicit expression.
• ServerAccess method ServerAccess changes or lists the server access-control entries. It requires tmux 3.3 and returns VersionTooLowError below that floor. List returns an owned snapshot, and reports a completed or transport failure rather than answering with no entries; mutation completed stderr is an error.
• Session method Session performs a canonical live lookup of id and returns a newly materialized record. Use Session.Refresh when beginning from a record.
• Sessions method Sessions materializes the server's sessions. Failures, including ErrNoServer, remain errors rather than empty results.
• SetBackspace method SetBackspace stores the "backspace" server option as string (tmux 3.2a or later). Read it with ServerOptionValues.Backspace from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetBuffer method SetBuffer stores or appends exact string data without refreshing models. It mutates the selected paste buffer; completed stderr is reported as a redacted command error because Data may be secret. Cancellation does not prove that tmux did not store data.
• SetBufferLimit method SetBufferLimit stores the "buffer-limit" server option as int64 (tmux 3.2a or later). Read it with ServerOptionValues.BufferLimit from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetClipboard method SetClipboard stores the "set-clipboard" server option as SetClipboard (tmux 3.2a or later). Read it with ServerOptionValues.SetClipboard from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetCodepointWidths method SetCodepointWidths replaces the complete "codepoint-widths" server option array with SparseArraystring, preserving holes and empty values (tmux 3.6 or later). Read it with ServerOptionValues.CodepointWidths from Server.Options ; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
• SetCommandAlias method SetCommandAlias replaces the complete "command-alias" server option array with SparseArraystring, preserving holes and empty values (tmux 3.2a or later). Read it with ServerOptionValues.CommandAlias from Server.Options ; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
• SetCopyCommand method SetCopyCommand stores the "copy-command" server option as string (tmux 3.2a or later). Read it with ServerOptionValues.CopyCommand from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetDefaultClientCommand method SetDefaultClientCommand stores the "default-client-command" server option as string (tmux 3.6 or later). Read it with ServerOptionValues.DefaultClientCommand from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetDefaultTerminal method SetDefaultTerminal stores the "default-terminal" server option as string (tmux 3.2a or later). Read it with ServerOptionValues.DefaultTerminal from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetEditor method SetEditor stores the "editor" server option as string (tmux 3.2a or later). Read it with ServerOptionValues.Editor from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetEnvironment method SetEnvironment stores a value in the server's global tmux environment. ExpandFormat and Hidden select tmux flags; cancellation does not prove the value was not stored.
• SetEscapeTime method SetEscapeTime stores the "escape-time" server option as int64 (tmux 3.2a or later). Read it with ServerOptionValues.EscapeTime from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetExitEmpty method SetExitEmpty stores the "exit-empty" server option as bool (tmux 3.2a or later). Read it with ServerOptionValues.ExitEmpty from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetExitUnattached method SetExitUnattached stores the "exit-unattached" server option as bool (tmux 3.2a or later). Read it with ServerOptionValues.ExitUnattached from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetExtendedKeys method SetExtendedKeys stores the "extended-keys" server option as ExtendedKeys (tmux 3.2a or later). Read it with ServerOptionValues.ExtendedKeys from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetExtendedKeysFormat method SetExtendedKeysFormat stores the "extended-keys-format" server option as ExtendedKeysFormat (tmux 3.5 or later). Read it with ServerOptionValues.ExtendedKeysFormat from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetFocusEvents method SetFocusEvents stores the "focus-events" server option as bool (tmux 3.2a or later). Read it with ServerOptionValues.FocusEvents from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetGetClipboard method SetGetClipboard stores the "get-clipboard" server option as GetClipboard (tmux 3.7 or later). Read it with ServerOptionValues.GetClipboard from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetHistoryFile method SetHistoryFile stores the "history-file" server option as string (tmux 3.2a or later). Read it with ServerOptionValues.HistoryFile from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetInputBufferSize method SetInputBufferSize stores the "input-buffer-size" server option as int64 (tmux 3.6 or later). Read it with ServerOptionValues.InputBufferSize from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetMessageLimit method SetMessageLimit stores the "message-limit" server option as int64 (tmux 3.2a or later). Read it with ServerOptionValues.MessageLimit from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetOption method SetOption stores a server-scope option without refreshing existing models. It may validate a known option against the live version. Completed failures return secret-safe option errors; cancellation does not prove the mutation was not accepted by tmux.
• SetPrefixTimeout method SetPrefixTimeout stores the "prefix-timeout" server option as int64 (tmux 3.5 or later). Read it with ServerOptionValues.PrefixTimeout from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetPromptHistoryLimit method SetPromptHistoryLimit stores the "prompt-history-limit" server option as int64 (tmux 3.3 or later). Read it with ServerOptionValues.PromptHistoryLimit from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• SetTerminalFeatures method SetTerminalFeatures replaces the complete "terminal-features" server option array with SparseArraystring, preserving holes and empty values (tmux 3.2a or later). Read it with ServerOptionValues.TerminalFeatures from Server.Options ; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
• SetTerminalOverrides method SetTerminalOverrides replaces the complete "terminal-overrides" server option array with SparseArraystring, preserving holes and empty values (tmux 3.2a or later). Read it with ServerOptionValues.TerminalOverrides from Server.Options ; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
• SetUserKeys method SetUserKeys replaces the complete "user-keys" server option array with SparseArraystring, preserving holes and empty values (tmux 3.2a or later). Read it with ServerOptionValues.UserKeys from Server.Options ; Server.UnsetOption restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
• SetVariationSelectorAlwaysWide method SetVariationSelectorAlwaysWide stores the "variation-selector-always-wide" server option as bool (tmux 3.6 or later). Read it with ServerOptionValues.VariationSelectorAlwaysWide from Server.Options ; Server.UnsetOption restores inheritance or the global default.
• ShowBuffer method ShowBuffer returns one buffer using Python-compatible line reconstruction. The returned string is owned by the caller; nil Name selects tmux's most recent buffer. Completed stderr is an error.
• ShowBufferBytes method ShowBufferBytes returns one buffer as exact caller-owned tmux stdout bytes. Unlike Server.ShowBuffer , it preserves invalid UTF-8, delimiters, and trailing newlines. Nil Name selects tmux's most recent buffer. Completed stderr returns a redacted command error and a nil byte slice.
• ShowEnvironment method ShowEnvironment returns an owned server-global non-hidden tmux environment. Completed command failures return an empty map unless strict errors are enabled. Externally injected multiline entries return ErrMalformedEnvironment because tmux's multi-entry output does not frame continuation lines. Decode errors are compatible with ErrMalformedEnvironment and return no partial map.
• ShowMessages method ShowMessages returns an owned snapshot of the tmux message log, terminal capabilities, job summary, or both terminal and job summaries. A zero TargetClient selects tmux's current client; a list failure is returned rather than answered with no rows.
• ShowPromptHistory method ShowPromptHistory returns an owned snapshot of tmux prompt-history lines. It requires tmux 3.3 or later and returns VersionTooLowError below that floor. A tmux command or transport failure is returned rather than answered with no history.
• Snapshot method Snapshot materializes sessions, winlinks, panes, and clients. Its sequential commands produce an observationally consistent result, not an atomic transaction. Failures remain errors rather than empty snapshots; cancellation may occur after earlier listings completed.
• SocketPath method SocketPath returns the absolute socket path selected when the server was constructed. An invalid server returns an empty string.
• SocketSelection method SocketSelection returns tmux's -S, -L, TMUX, and default-socket precedence snapshotted by NewServer . It does not start tmux or require the selected socket to exist.
• SourceFile method SourceFile loads or parses one tmux configuration file. The path expands ~ and ~/... for the current user and normalizes redundant separators and dot components without collapsing parent components. Named-user forms are rejected. Exact "-" is rejected because it requires process stdin; a relative path naming a file called "-" remains file data. It can mutate tmux configuration; completed stderr is an error, and cancellation does not prove that parsing or sourcing did not occur.
• Start method Start starts the configured tmux server. It is idempotent when that server is already running. Completed stderr is an error; cancellation does not prove that a daemon was not started.
• String method String returns a concise representation of the server selector.
• SuspendClient method SuspendClient suspends a client, or tmux's current client when targetClient is nil. Cancellation does not prove suspension did not occur.
• SwitchClient method SwitchClient switches tmux's current client to targetSession. TargetSession is a validated session name rather than a stable identity; cancellation does not prove the switch did not occur.
• UnbindKey method UnbindKey removes one key binding or every binding in a key table. Key and AllKeys must select exactly one target; cancellation does not prove removal did not occur.
• UnsetEnvironment method UnsetEnvironment deletes a value from the server's global tmux environment. Cancellation does not prove deletion did not occur.
• UnsetOption method UnsetOption unsets a server-scope option without refreshing existing models. UnsetPanes is invalid at server scope. Completed failures are secret-safe option errors; cancellation does not prove the unset was not accepted.
• Version method Version returns the configured tmux binary's cached version. Failed probes are not cached. A waiting caller can abandon an in-flight shared probe when ctx ends without canceling the caller that owns the probe.
• WaitFor method WaitFor waits for, signals, locks, or unlocks a named tmux channel. It changes only that server-side channel state; cancellation can interrupt the client wait but cannot prove a preceding signal or lock did not take effect.
• Window method Window performs a canonical live lookup of id using tmux's canonical session and returns a newly materialized record. It does not preserve a linked-session view; use Window.ResolveSession for that exact relationship.
• Windows method Windows materializes one record per winlink. Failures, including ErrNoServer, remain errors rather than empty results.
• WithSocketPath method WithSocketPath returns a server using path and the receiver's frozen executable, environment, working directory, and server-option policy. Empty clears explicit socket selectors and leaves endpoint selection to tmux. The result has fresh daemon-scoped coordination. A connection-bound receiver is rejected because its transport belongs to the original daemon.