C++ API

method libtmux-cxx latest

Session.panes

Source and package

Qualified name: libtmux::Session::panes
Namespace: libtmux
Declared in: Session
Package: libtmux-cxx
Source: include/libtmux/entities.hpp
Other languages: Perl Erlang PowerShellcmdlet Julia Elixir Haskell Common Lispfunction PythonRuby Lua TypeScriptRustGo Java C#Swift Kotlin Scala OCaml F#function Clojure

[[C++ nodiscard attributeAsks the compiler to warn when a result is discarded. An explicit cast to void acknowledges that the result is intentionally ignored.Language documentation]] expected<std::vector<Pane>, CommandFailure> panes() const; method readonly [source] ¶

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.

tmux command#

The tmux commands behind panes.

list-panes -s session scope, cmd_list_panes_session

tmux C API#

The C declarations in tmux that implement these commands.

cmd_list_panes_entry cmd_list_panes_session

Guides#

Pages that discuss panes.

Traversal

In other ports#

List a session's panes

Equivalents of List a session's panes in other languages
Language	Equivalent
Python	`libtmux.Session.panes`
Ruby	`LibTmux::Session#list_panes`
PowerShell	`LibTmux\Get-TmuxPane` Use the `-Session` parameter set to acquire panes across that session’s windows.
Julia	Traverse `windows(session)` and `panes(window)` in the captured snapshot. `panes(snapshot)` has server-wide scope.
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
Common Lisp	`libtmux:panes` `panes` traverses captured observations; applying it to a session returns panes reachable through its retained links.
TypeScript	`session.Session.panes`
Rust	`session.Session.panes`
Go	`tmux.Session.Panes`
Java	no direct accessor; traverse Session.windows and Window.panes
C#	`LibTmux.Session.Panes`
F#	`LibTmux.FSharp.Session.panes` Builds a deferred pane query from one `LibTmux.Session` and its server. `Query.list` acquires panes across that session’s windows.
Swift	`Snapshot.panes(of:)`
OCaml	Traverse Session.windows and Window.panes in the captured graph. Snapshot.panes has server-wide scope.
Perl	Traverse the session’s window links and physical windows; choose explicitly whether repeated linked panes should repeat.

No equivalent is recorded in Lua, Erlang, Elixir, Clojure, Kotlin or Scala.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Session.panes

Examples#

tmux command#

tmux C API#

Guides#

In other ports#

Examples#

tmux command#

tmux C API#

Guides#

In other ports#

Related types#