C++ API

method libtmux-cxx latest

Pane.capture

The visible contents, as tmux printed them.

Source and package

Qualified name: libtmux::Pane::capture
Namespace: libtmux
Declared in: Pane
Package: libtmux-cxx
Source: include/libtmux/entities.hpp
Other languages: Perlmethod Erlang PowerShell Julia Elixir Haskell Common Lisp PythonRubyLuaTypeScriptRustGoJavaC#SwiftKotlinScalaOCamlF#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::string, CommandFailure> capture() const;[[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::string, CommandFailure> capture(CaptureOptions options) const; method readonly overload 2 overloads [source] ¶

Description#

capture_lines() frames it into lines, and takes a named string: the lines are views into it, so framing this return value directly is a compile error rather than a dangling read.

A pane's scrollback can be far larger than the default bound, and a capture that does not fit is reported rather than cut, so a caller reading history passes the size it is prepared to hold.

Examples#

Send input and capture confirmed output. Start a small shell reader with terminal echo disabled, wait for readiness, send one line, and capture its response. The two bounded waits prevent startup races and confirm output from the program. The final cat keeps the pane available for capture until cleanup. 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 <algorithm>
#include <chrono>
#include <cstdio>
#include <ranges>

#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 window = sessions->front().new_window(libtmux::NewWindowOptions{
      .name = "reader",
      .shell_command = R"(exec sh -c '
        stty -echo
        printf "ready\n"
        IFS= read -r line
        printf "got:%s\n" "$line"
        exec cat >/dev/null
      ')",
  });
  if (!window.has_value()) {
    std::fprintf(stderr, "%s\n", window.error().diagnostic.c_str());
    return 1;
  }
  const auto pane = window->active_pane();
  if (!pane.has_value()) {
    std::fprintf(stderr, "%s\n", pane.error().diagnostic.c_str());
    return 1;
  }
  const auto ready = pane->wait_for_text("ready", {.timeout = std::chrono::seconds{5}});
  if (!ready.has_value()) {
    std::fprintf(stderr, "%s\n", ready.error().diagnostic.c_str());
    return 1;
  }
  if (!ready->matched) {
    std::fputs("reader did not become ready\n", stderr);
    return 1;
  }
  const auto text = pane->send_text("hello ");
  if (!text.has_value()) {
    std::fprintf(stderr, "%s\n", text.error().diagnostic.c_str());
    return 1;
  }
  const auto line = pane->send_line("C++");
  if (!line.has_value()) {
    std::fprintf(stderr, "%s\n", line.error().diagnostic.c_str());
    return 1;
  }
  const auto answered =
      pane->wait_for_text("got:hello C++", {.timeout = std::chrono::seconds{5}});
  if (!answered.has_value()) {
    std::fprintf(stderr, "%s\n", answered.error().diagnostic.c_str());
    return 1;
  }
  if (!answered->matched) {
    std::fputs("reader did not confirm the input\n", stderr);
    return 1;
  }
  const auto captured = pane->capture();
  if (!captured.has_value()) {
    std::fprintf(stderr, "%s\n", captured.error().diagnostic.c_str());
    return 1;
  }
  // The captured string outlives the line views returned by capture_lines.
  const auto lines = libtmux::capture_lines(*captured);
  if (std::ranges::find(lines, "got:hello C++") == std::ranges::end(lines)) {
    std::fputs("captured output does not contain the response\n", stderr);
    return 1;
  }
  std::puts("got:hello C++");
  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:

got:hello C++

Parameters

options (CaptureOptions) # for capture(options)

tmux command#

The tmux commands behind capture.

capture-pane

tmux C API#

The C declarations in tmux that implement these commands.

cmd_capture_pane_entry cmd_capture_pane_exec

Guides#

Pages that discuss capture.

In other ports#

Read a pane’s visible contents

Equivalents of Read a pane’s visible contents in other languages
Language	Equivalent
Python	`libtmux.Pane.capture_pane`
Ruby	`LibTmux::Pane#capture`
Lua	`libtmux.Pane:capture`
Erlang	`tmux_pane:capture/2`
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
TypeScript	`pane.Pane.capture`
Rust	`pane.Pane.capture`
Go	`tmux.Pane.Capture`
Java	`io.github.libtmux.Pane.capture`
Clojure	`libtmux.core/capture!`
Kotlin	`io.github.libtmux.kotlin.Pane.capture`
Scala	`io.github.libtmux.scaladsl.Pane.capture`
C#	`LibTmux.Pane.CaptureAsync`
F#	`LibTmux.FSharp.Pane.capture`
Swift	`Server.capture(_:includingHistory:)`
OCaml	`Libtmux_unix.Client.capture_text`
Perl	`LibTmux::Server::capture_pane` Explicit Server operation. Captured entities remain local observations; use a new snapshot to observe changes.

No equivalent is recorded in PowerShell, Julia, Elixir or Common Lisp.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Pane.capture

Description#

Examples#

tmux command#

tmux C API#

Guides#

In other ports#

Description#

Examples#

tmux command#

tmux C API#

Guides#

In other ports#

Related types#