C++ API

class libtmux-cxx latest

Session

One session, as one listing saw it.

Source and package

Qualified name: libtmux::Session
Namespace: libtmux
Package: libtmux-cxx
Source: include/libtmux/entities.hpp
Other languages: Perlclass ErlangPowerShellcmdlet Juliastruct Elixirstruct Haskell Common Lispclass PythonRubyLuaTypeScriptRustGoJavaC#SwiftKotlinScalaOCamlF#module Clojurefunction

class libtmux::Session class [source] ¶

Description#

Reads its own fields without touching tmux: the listing ran once, and every value here is that moment's. A window created since is not in window_count(), and a session killed since still answers.

Equality is the server incarnation and the session id together, so two handles from separate listings of one live server agree, and a handle kept across a restart does not become a handle to whatever reused $0.

Examples#

Traverse a session and its children. List windows and panes within one session, then follow a pane back to its owning window and session. Each relation method performs a new read; the original entity still holds its earlier snapshot. 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:

$ git clone https://github.com/libtmux/libtmux-cxx.git libtmux-source && \
  git -C libtmux-source checkout 542fdc204ff3cfa56f5484327cda0c69bad2307d

Build and install the C++23 library and its public testing component into this directory:

$ 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 source

cmake_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. ScopedTmuxServer owns a private daemon and stops it when the program exits. Ordinary applications use Server for 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;
  }

  const auto sessions = server->sessions();
  if (!sessions.has_value()) {
    std::fprintf(stderr, "%s\n", sessions.error().diagnostic.c_str());
    return 1;
  }
  if (sessions->size() != 1) {
    std::fputs("expected one session\n", stderr);
    return 1;
  }
  const auto& session = sessions->front();
  const auto windows = session.windows();
  const auto session_panes = session.panes();
  if (!windows.has_value()) {
    std::fprintf(stderr, "%s\n", windows.error().diagnostic.c_str());
    return 1;
  }
  if (!session_panes.has_value()) {
    std::fprintf(stderr, "%s\n", session_panes.error().diagnostic.c_str());
    return 1;
  }
  if (windows->size() != 1 || session_panes->size() != 1) {
    std::fputs("expected one window and pane\n", stderr);
    return 1;
  }
  const auto& window = windows->front();
  const auto panes = window.panes();
  if (!panes.has_value()) {
    std::fprintf(stderr, "%s\n", panes.error().diagnostic.c_str());
    return 1;
  }
  if (panes->size() != 1) {
    std::fputs("expected one window pane\n", stderr);
    return 1;
  }
  const auto owner_window = panes->front().window();
  const auto owner_session = panes->front().session();
  if (!owner_window.has_value()) {
    std::fprintf(stderr, "%s\n", owner_window.error().diagnostic.c_str());
    return 1;
  }
  if (!owner_session.has_value()) {
    std::fprintf(stderr, "%s\n", owner_session.error().diagnostic.c_str());
    return 1;
  }
  if (*owner_window != window || *owner_session != session ||
      panes->front() != session_panes->front()) {
    std::fputs("entity ownership does not match\n", stderr);
    return 1;
  }
  std::puts("api session -> one window -> one pane; owners match.");
  return 0;
}

Build against the installed library and run the saved program. An operation error produces a failing exit status:

$ 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_example

Expected output:

api session -> one window -> one pane; owners match.

Members34#

Parent objects1#

server method inherited The server this entity came from, for a command the typed surface does not cover.

Collections and queries2#

windows method
panes method

Common operations25#

new_window method Created detached: a library call that stole the terminal would be a surprise, and attaching is a separate decision.
kill method
rename method
hooks method
id method
name method
attached method session_attached counts clients rather than rendering a flag, so any count other than zero means attached.
options method Session options.
set_option method
unset_option method Remove the value set here, so the wider scope shows through again.
set_hook method
option method
created method
detach_clients method Send every client here away, leaving the session running.
active_window method
active_pane method
refresh method
select_next_window method Move the selection, and answer with the window it landed on.
select_previous_window method
select_last_window method
attach_command method A command line that attaches a terminal to this session.
window_count method
path method The directory a new window starts in, not the shell's current directory.
group method Empty unless the session belongs to a group sharing its windows.
grouped method

Other members6#

client_count method
expand method Ask tmux to expand a format against this session.
kFields: std::array attribute
kNoun: std::string_view attribute
Session method
show_message method Put a message on the status line of every client attached here, and send it to a control client as message.

Guides#

Pages that discuss Session.

Concepts: Server, session, window, pane
Topics: Architecture
Ownership and cleanup
Format-token fields
Traversal

In other ports#

A tmux session

Equivalents of A tmux session in other languages
Language	Equivalent
Python	`libtmux.Session`
Ruby	`LibTmux::Session`
Lua	`libtmux.Session`
PowerShell	`LibTmux\Get-TmuxSession` This cmdlet reads and returns shared .NET `LibTmux.Session` objects. Child windows and panes require further acquisition.
Julia	`LibTmux.SessionSnapshot` `SessionSnapshot` holds captured session data. Actions use its `SessionRef`, a typed identity bound to an observed daemon generation.
Erlang	`#tmux_model:session{}`
Elixir	`LibTmux.Session` `Session` is an immutable observation. Fields not captured read as `:unloaded`.
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
Common Lisp	`libtmux:session` `session` is an immutable captured entity. The same name also has a relation accessor with a distinct public identity.
TypeScript	`session.Session`
Rust	`session.Session`
Go	`tmux.Session`
Java	`io.github.libtmux.Session`
Clojure	`libtmux.core/sessions!` Acquires a vector of captured session maps. The session value is a map, not a wrapper class.
Kotlin	`io.github.libtmux.kotlin.Session`
Scala	`io.github.libtmux.scaladsl.Session`
C#	`LibTmux.Session`
F#	`LibTmux.FSharp.Session` This F# module builds deferred child queries from a shared .NET `LibTmux.Session` and its server association. `Query.list` acquires their results from tmux.
Swift	`Session`
OCaml	`Libtmux.Session.t`
Perl	`LibTmux::Session` A captured read-only entity; explicit Server operations accept its stable identity.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Session

Description#

Examples#

Members34#

Parent objects1#

Collections and queries2#

Common operations25#

Other members6#

Guides#

In other ports#

Description#

Examples#

Members34#

Parent objects1#

Collections and queries2#

Common operations25#

Other members6#

Guides#

In other ports#

Related types#