# server.Server

- **Module:** server
- **Package:** libtmux
- **Language:** Rust
- **Kind:** struct
- **Source:** https://github.com/libtmux/libtmux-rs/blob/f0e37052c232636b61d095817046e6bfc8f2ca40/crates/libtmux/src/server.rs#L361
- **Page:** https://libtmux.org/en/rs/latest/reference/server-server/

A cloneable handle to one captured tmux server endpoint.

Equality and hashing use only the captured [`ServerIdentity`]. Clones share
capability detection, request IDs, and executor shutdown state.
Dropping a handle is nonblocking and does not stop the tmux daemon. Runtime
owners should await [`Server::shutdown`] before tearing down Tokio when
deterministic client-child cleanup is required.

# What is on here

A tmux server does a great many things, so this type has a great many
methods. They fall into a few groups:

**Connecting.** [`new`] takes the default socket, [`builder`] configures
one, and [`from_env`] reads the server this process is already inside.
[`is_alive`] and [`check_alive`] answer whether anything is listening.

**Finding one thing.** [`session`] and [`client`] take names;
[`session_by_id`], [`window_by_id`], and [`pane_by_id`] take tmux IDs.
Each reports `Ok(None)` when tmux does not have it.

**Listing everything.** [`sessions`], [`windows`], [`panes`], and
[`clients`]. Each keeps the reason it failed, so an outage does not read
as an empty server. [`hierarchy`] gathers the whole tree in
three tmux commands rather than one per object.

**Changing things.** [`new_session`], [`kill`], and [`with_session`],
which cleans up after itself whether the body succeeded or not.

**Options and hooks.** [`typed_option`] and [`set_typed_option`] for this
server, [`typed_global_option`] and [`set_typed_global_option`] for the
session defaults, [`set_option`] to send text tmux's option table does not
check, and [`set_hook`] and [`unset_hook`]. [`OptionValue`] says how the
reads and writes fit together.

**Everything else tmux keeps.** Paste buffers ([`buffer`], [`set_buffer`],
[`buffer_names`], [`delete_buffer`]), key bindings ([`bind_key`],
[`unbind_key`], [`key_bindings`]), format expansion ([`format`]),
configuration ([`source_file`]), shell commands ([`run_shell`],
[`spawn_shell`]), and wait-for channels ([`lock_channel`],
[`unlock_channel`], [`signal_channel`]).

**Things that need a terminal.** [`display_popup`], [`display_menu`],
[`command_prompt`], [`choose`], [`find_window`], and [`display_panes`] all
draw on an attached client, and fail without one.

Anything tmux can do that is not here is reachable through [`cmd`], which
runs an arbitrary command and hands back its result.

## Example

```rust
use libtmux::test::TestServer;

// In your own code this is `libtmux::Server::new()?`; the fixture keeps
// the example off whichever tmux you are actually using.
let guard = TestServer::new().await?;
let server = guard.server();

server.new_session("work").await?;
assert_eq!(server.sessions().await?.len(), 1);

guard.shutdown().await?;
```

## Members

- `owns_control_client` (method): Report whether this process itself opened the control client with this pid, and it is still running.
- `new` (method): Construct a server from the captured default endpoint context.
- `builder` (method): Start a consuming server builder.
- `identity` (method): Return the captured structural endpoint identity.
- `socket_path` (method): Return the captured absolute socket path used for identity and dispatch.
- `socket_name` (method): Return the configured named socket selector, if any.
- `config_file` (method): Return the captured config path, if configured.
- `colors` (method): Return the configured tmux color mode.
- `tmux_executable` (method): Return the captured tmux executable value.
- `resolved_tmux_executable` (method): Resolve the configured tmux executable from the captured launch context.
- `default_timeout` (method): Return the captured per-command timeout.
- `capabilities` (method): Detect and share capabilities for the configured tmux executable.
- `cmd` (method): Execute one raw logical tmux command.
- `chain` (method): Dispatch several commands as one `tmux a \; b` invocation.
- `shutdown` (method): Stop accepting clients and wait for every active client process.
- `from_env` (method): Build a server from the `TMUX` variable tmux exports into every pane.
- `from_env_value` (method): Build a server from an explicit `TMUX` value.
- `attached_sessions` (method): List the sessions that have at least one client attached.
- `new_session` (method): Create a detached session and return it.
- `lock_all` (method): Lock every client on the server.
- `kill` (method): Stop the tmux daemon at this endpoint.
- `set_buffer` (method): Store data in a tmux paste buffer.
- `load_buffer` (method): Fill a paste buffer from a file, letting tmux read it.
- `save_buffer` (method): Write a paste buffer to a file, letting tmux do the writing.
- `buffer` (method): Read a paste buffer's exact bytes.
- `buffer_names` (method): List the paste buffer names.
- `delete_buffer` (method): Delete one paste buffer.
- `bind_key` (method): Bind a key in one key table.
- `unbind_key` (method): Remove a key binding from one key table.
- `key_bindings` (method): List key bindings as tmux prints them.
- `format` (method): Expand a tmux format string and return the result.
- `prompt_history` (method): The entries tmux remembers for one kind of prompt.
- `clear_prompt_history` (method): Forget the entries tmux remembers for prompts.
- `access_rules` (method): The users on this server's access list.
- `grant_access` (method): Let a user attach to this server.
- `revoke_access` (method): Stop a user attaching to this server.
- `source_file` (method): Load a tmux configuration file into this server.
- `with_session` (method): Create a session, run an operation with it, then kill it.
- `run_shell` (method): Run a shell command through tmux and collect its output.
- `spawn_shell` (method): Run a shell command in the background and return immediately.
- `start` (method): Start a tmux server without creating a session.
- `generation` (method): Which tmux daemon is answering on this endpoint.
- `require_generation` (method): Fail unless the daemon answering is still the one that was captured.
- `is_alive` (method): Report whether a tmux daemon is answering at this endpoint.
- `check_alive` (method): Require a tmux daemon to be answering at this endpoint.
- `over_control_mode` (method): Return a handle whose commands run over an open control connection.
- `signal_channel` (method): Signal a `wait-for` channel, releasing anything waiting on it.
- `with_channel_lock` (method): Hold a `wait-for` channel for the length of an operation.
- `lock_channel` (method): Lock a `wait-for` channel, blocking later lock attempts on it.
- `unlock_channel` (method): Unlock a `wait-for` channel.
- `wait_for_channel` (method): Wait for a `wait-for` channel to be signalled.
- `windows` (method): List every window on the server, preserving any failure.
- `panes` (method): List every pane on the server, preserving any failure.
- `clients` (method): List every client attached to the server, preserving any failure.
- `session` (method): Find the session with this exact name.
- `session_by_id` (method): Find the session with this id.
- `window_by_id` (method): Find the window with this id, through the first link that reaches it.
- `pane_by_id` (method): Find the pane with this id.
- `client` (method): Find the client attached to this terminal.
- `hierarchy` (method): Fetch the whole hierarchy in three commands.
- `has_session` (method): Report whether a session with this exact name exists.
- `sessions` (method): List every session on the server, preserving any failure.
- `display_popup` (method): Show a popup over a client, running a command inside it.
- `display_menu` (method): Show a menu over a client.
- `command_prompt` (method): Open a command prompt on a client.
- `choose` (method): Open one of tmux's interactive choosers on a client.
- `find_window` (method): Open tmux's window finder for a search string.
- `display_panes` (method): Briefly show each pane's number on a client.
- `typed_key_bindings` (method): List key bindings as fields: table, key, command, note and repeat.
- `option_names` (method): List the server option names.
- `options` (method): Read every option set at this server, decoded by its declared kind.
- `set_option` (method): Set one server option to text, unchecked.
- `set_typed_option` (method): Set one server option to a typed value, checked before it is sent.
- `unset_option` (method): Remove one server option.
- `set_global_option` (method): Set one global session option to text, unchecked.
- `set_typed_global_option` (method): Set one global session option to a typed value, checked before it is sent.
- `set_environment` (method): Set a variable in the server's own environment.
- `environment` (method): Read one variable from the server's environment.
- `environment_all` (method): Read the server's whole environment.
- `hide_environment` (method): Hide a variable from processes tmux starts.
- `unset_environment` (method): Remove a variable from the server's environment.
- `array_option` (method): Read every value an array option holds, by index.
- `set_array_option` (method): Write one index of an array option, leaving the others alone.
- `append_array_option` (method): Extend the value already at one index of an array option.
- `unset_array_option` (method): Remove one index of an array option, leaving a gap where it was.
- `set_global_window_option` (method): Set one global window option to text, unchecked.
- `set_typed_global_window_option` (method): Set one global window option to a typed value, checked before it is sent.
- `set_hook` (method): Set one global hook.
- `unset_hook` (method): Remove one global hook.
- `set_hooks` (method): Write a whole hook at once.
- `hooks` (method): Read every hook set at this server.
- `hook` (method): Read one hook's commands, or `None` when it holds nothing.
- `typed_option` (method): Read one server option, decoded according to its declared kind.
- `typed_global_option` (method): Read one global session option, decoded according to its declared kind.
- `typed_global_window_option` (method): Read one global window option, decoded according to its declared kind.