Server
One tmux server, addressed by the socket it listens on.
Source and package
-
Description#
The entry point: sessions, windows and panes are read from here and carry the server with them. Constructing a handle sends no command. Only a startable handle may create an absent daemon; ordinary handles never do.
A Server is a handle. Copying one costs a reference count, and every entity read from it keeps the same connection alive, so a listing outlives the Server value that produced it. The connection is fixed at construction, which is what makes a Server safe to copy between threads. Apart from
is_alive(), which answersbool, a call that reaches tmux returns anexpected, and the library does not throw to report a tmux failure.What is on here
The members fall into a few groups.
- Connecting
at_socket_path()andat_socket_name()choose a socket by path (-S) or by name (-L),at_default()takes the one tmux picks when the caller names none, andfrom_env()reads the server this process is already inside.startable_at_socket_path(),startable_at_socket_name()andstartable_at_default()build handles that may create an absent server, andover()builds a handle over a transport you supply.is_alive()andcheck_alive()answer whether anything is listening, the second keeping the reason when nothing is.capabilities()says what the handle may rely on and runs no command; on psmux that is exact inspection and namespace cleanup only. Most typed calls outside it reportFailureKind::unsupportedthere;control()andover_control()report aProtocolErrorinstead, and the environment calls and raw commands are not checked.tmux_version()reports the tmux release, andsocket_path()reports the resolved socket.control()andcontrol_with_options()open a control-mode connection to one session, andover_control()returns a Server whose commands travel over held-open control clients.- Finding one thing
- Look up a session, window or pane by a target, such as an id or a
session:windowpath. The lookup resolves the target the way tmux does: a session target names that session's active pane and the window that pane is in. A target tmux cannot resolve comes back as aFailureKind::missingfailure. - Listing everything
- Each listing is one snapshot: iterating or filtering it never reaches tmux again, and a current view needs a fresh call. The window and pane listings span every session.
- Querying things and getting around
- A listing already in memory is filtered without tmux:
matching()takes aFilterExprbuilt from an entity's typed fields, andexactly_one()takes the single match, borrowing it from the listing, whereexactly_one_owned()takes a copy. Both reportCardinalityError::none_matchedorCardinalityError::several_matchedotherwise.children_of()andparent_of()join two listings on an id so a filter can ask about related rows. To move between levels, go down withSession::windows(),Session::panes()andWindow::panes(), up withPane::window(),Pane::session(),Window::session()andClient::session(), and across to the active window or pane withSession::active_window(),Session::active_pane()andWindow::active_pane(). Each of those asks tmux, so each can fail. - Changing things
new_session()creates a session detached and returns it, andkill()ends the server and everything in it.- Options and hooks
options(),server_options(),global_options(),hooks()andglobal_hooks()read them,global_hooks()being how a hook set globally is read back, sincehooks()without a target does not report it;set_server_option(),set_global_option()andset_global_hook()write them. The environment every new process starts with isenvironment(), withset_environment()to bind a name,unset_environment()to forget it, andremove_environment()to keep the name but take it out of what a process inherits.- Everything else tmux keeps
- Paste buffers:
buffers()lists them,set_buffer()fills one, andload_buffer()andsave_buffer()move one to and from a file the tmux server reads or writes. Key bindings:bind_key()andunbind_key().commands()lists every command this tmux understands,expand()expands a format against the server alone,source_file()runs a configuration file andcheck_file()reports what tmux would refuse in it without running any, andvalidate_layouts()checks saved layouts without applying them.run_shell()reports whether a shell command ran, not what it printed, andshow_message()puts a message on every attached client's status line.wait_for()blocks untilsignal()releases a channel, and with no timeout never gives up;wait_for_text()waits for the pane a target names to produce some text. - Things that need a terminal
- None are here: every command this library runs talks to tmux through pipes.
Session::attach_command()returns the argv for a terminal you own to run. - Running a command
- Anything tmux can do that is not here is reachable through
run(), which runs one command;run_batch()andrun_chain()run several, andtry_submit()admits one to aCommandRuntimewithout waiting for it.
Examples#
Connect to an owned server. Construct a Server handle for an explicit socket. Construction sends no command; sessions() reads the running server. The fixture controls daemon lifetime, while copies of Server share the connection. libtmux-cxx is not published to a package registry yet, so this builds it from its repository. Use Clang 18 or newer with libc++, CMake 3.25 or newer, Ninja, Git, and tmux 3.3a or newer on Linux. In an empty directory, fetch the documented library revision:
Terminal window $ git clone https://github.com/libtmux/libtmux-cxx.git libtmux-source && \git -C libtmux-source checkout 542fdc204ff3cfa56f5484327cda0c69bad2307dBuild and install the C++23 library and its public testing component into this directory:
Terminal window $ cmake -S libtmux-source -B libtmux-build -G Ninja \-DCMAKE_TOOLCHAIN_FILE="$PWD/libtmux-source/cmake/toolchains/clang-libcxx.cmake" \-DCMAKE_C_COMPILER=clang \-DCMAKE_CXX_COMPILER=clang++ \-DCMAKE_BUILD_TYPE=Release \-DLIBTMUX_BUILD_TESTS=OFF \-DLIBTMUX_BUILD_EXAMPLES=OFF \-DLIBTMUX_BUILD_TESTING_LIBRARY=ON && \cmake --build libtmux-build --parallel 2 && \cmake --install libtmux-build --prefix "$PWD/libtmux-prefix"Save this complete consumer project as
CMakeLists.txt: View sourcecmake_minimum_required(VERSION 3.25)project(libtmux_api_example LANGUAGES CXX)find_package(libtmux REQUIRED COMPONENTS testing)add_executable(api_example main.cpp)target_link_libraries(api_example PRIVATE libtmux::libtmux libtmux::testing)Save this complete program as
main.cpp.ScopedTmuxServerowns a private daemon and stops it when the program exits. Ordinary applications useServerfor their own socket; these examples use the fixture until setup moves to ordinary server objects. View source#include <cstdio>#include <libtmux/libtmux.hpp>#include <libtmux/testing/scoped_server.hpp>int main() {// The fixture owns this private server and cleans it up on every return path.auto fixture = libtmux::test::ScopedTmuxServer::start({.session_name = "api",.socket_namespace = libtmux::test::SocketNamespace::consumer("api"),});if (!fixture.has_value()) {std::fprintf(stderr, "%s\n", fixture.error().c_str());return 1;}auto server = libtmux::Server::at_socket_path(fixture->socket_path());if (!server.has_value()) {std::fprintf(stderr, "%s\n", server.error().diagnostic.c_str());return 1;}// Copying the handle keeps the same connection; it does not start another server.const libtmux::Server copy = *server;const auto sessions = copy.sessions();if (!sessions.has_value()) {std::fprintf(stderr, "%s\n", sessions.error().diagnostic.c_str());return 1;}if (copy.socket_path() != fixture->socket_path().string() || sessions->size() != 1 ||sessions->front().name() != "api") {std::fputs("unexpected server or session\n", stderr);return 1;}std::puts("Connected to the private api session.");return 0;}Build against the installed library and run the saved program. An operation error produces a failing exit status:
Terminal window $ cmake -S . -B build -G Ninja \-DCMAKE_PREFIX_PATH="$PWD/libtmux-prefix" \-DCMAKE_CXX_COMPILER=clang++ \-DCMAKE_CXX_FLAGS=-stdlib=libc++ && \cmake --build build --parallel 2 && \./build/api_exampleExpected output:
Connected to the private api session.
Members58#
Collections and queries6#
- sessions method One snapshot each.
- windows method tmux scopes window and pane listings to the current session unless asked for every one, so
-ais part of the request rather than a caller's responsibility to remember. - panes method
- clients method
- buffers method The server's cut buffers, newest first as tmux orders them.
- commands method Every command this tmux understands, with its alias and usage.
Common operations28#
- new_session method Created detached, and returned, because tmux prints what it made.
- kill method End the server and everything in it.
- hooks method
- source_file method Run the commands in a file, the way tmux runs a configuration file.
- options method
- set_buffer method Put text in a named buffer, replacing what was there.
- set_server_option method
- wait_for method Block until someone signals this channel, or the deadline passes.
- is_alive method Whether a server is answering on this socket.
- run_shell method Run a shell command on the machine the server is on.
- session method One object by target, for a caller holding an id or a
session:windowpath that came from somewhere else. - window method
- pane method
- load_buffer method Read a file into a named buffer, and write one back out.
- bind_key method Bind a key in a key table, and take a binding away again.
- unbind_key method Unbinding a key that was not bound succeeds; unbinding in a table that does not exist is refused.
- save_buffer method
- set_global_option method Sets the value every session inherits, rather than one session's own.
- show_message method Put a message on the status line of every attached client, and send it to each control client as
message. - run_chain method Run a chain.
- from_env method The server this process is running inside.
- global_options method
- at_socket_path method
-S path: the socket file, used verbatim. - at_default method The server a bare
tmuxcommand reaches from this process, unless the environment names another: the one a person means when they say "my tmux". - at_socket_name method
-L name: resolved under tmux's socket directory, as the tmux flag does. - control method Open a control-mode connection to one session.
- global_hooks method A hook set globally is not reported by the unscoped listing, so reading it back needs the scope it was set with.
- signal method Release whoever is waiting on the channel, or latch it for whoever waits next.
Other members24#
- capabilities method The local backend contract; no command runs.
- check_alive method The same question, keeping why the answer was no.
- check_file method Parse the same file and report what tmux would refuse in it, running none of it.
- check_release method Refuse a tmux below the floor exactly as the first command to this endpoint would, and send nothing.
- control_with_options method The Server supplies the socket and
session()supplies the session name; every other connection option is kept, including pane output policy. - environment method The environment every new process on this server starts with.
- expand method Ask tmux to expand a format, against no target but the server itself.
- over method A Server over a transport the caller supplies.
- over_control method A Server whose commands travel over held-open control clients attached to
session(), rather than one launched process each. - remove_environment method Keep the name and take it out of what a new process inherits — tmux's
-r, which a listing then prints as-NAME. - run method Run one command and return its standard output.
- run_batch method Run several commands in one invocation.
- server_options method The server's own options, which are neither session nor window options and are the only ones a server without a session still has.
- set_environment method Bind a name.
- set_global_hook method
- socket_path method The resolved path pinned by this handle, including a startable path whose server has not been created yet.
- startable_at_default method
at_default(), for a handle that may create an absent server. - startable_at_socket_name method
- startable_at_socket_path method A socket handle that may create an absent server on its first
new_session()call or an explicitrun({"start-server"}). - tmux_version method The release behind this handle: the daemon's when one answers, and otherwise the executable that would start one, read with
tmux -V. - try_submit method Admit one command to an explicit bounded runtime without waiting for it.
- unset_environment method Forget the name, so a new process inherits whatever the tmux server itself has.
- validate_layouts method Validate the complete batch's syntax before any I/O, then ask for the release once for version-dependent names or v2 JSON layouts: the daemon's when one answers, otherwise the executable's.
- wait_for_text method Wait until the pane
targetnames produceswanted.
Guides#
Pages that discuss Server.
- Concepts
- Examples
In other ports#
A tmux server
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| Lua | libtmux |
| PowerShell | Lib This cmdlet constructs a shared .NET LibTmux.Server handle without contacting tmux. |
| Julia | Lib Server describes an endpoint without contacting tmux. Read its hierarchy with snapshot. |
| Erlang | tmux open/1 observes an existing daemon and starts an endpoint owner. Domain rows remain immutable values. |
| Elixir | Lib Server describes an existing server by executable and socket. It neither connects nor reserves the server’s identity. |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| TypeScript | server |
| Rust | server |
| Go | tmux |
| Java | io |
| Clojure | libtmux Opens a closeable Java server client for an explicit endpoint. Acquisitions return persistent maps with explicit Java references for effects. |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| F# | Lib This F# module provides functions over the shared .NET LibTmux.Server type. |
| Swift | Server |
| OCaml | Libtmux A client is a live, generation-bound server connection. Endpoint describes a socket without connecting; closing a client releases its resources. |
| Perl | Lib Construction records connection settings without tmux I/O. Optional LibTmux::Async::Server returns standard Future results for operations. |
No equivalent is recorded in Common Lisp.