C++ API

struct libtmux-cxx latest

NewSessionOptions

What a new session is created as, including its first window.

Source and package

Qualified name: libtmux::NewSessionOptions
Namespace: libtmux
Package: libtmux-cxx
Source: include/libtmux/entities.hpp

struct libtmux::NewSessionOptions struct [source] ¶

Description#

tmux always creates a first window, so the fields naming one are not optional in effect — leaving them empty takes tmux's defaults rather than creating nothing.

Examples#

Create a detached session. Create a detached session with a named first window, then read back its name and owner. The cat process keeps the first pane alive until fixture cleanup. A fresh listing sees both the fixture session and the new session. 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 made = server->new_session(libtmux::NewSessionOptions{
      .name = "work",
      .first_window_name = "main",
      .shell_command = "exec cat",
  });
  if (!made.has_value()) {
    std::fprintf(stderr, "%s\n", made.error().diagnostic.c_str());
    return 1;
  }
  const auto window = made->active_window();
  const auto sessions = server->sessions();
  if (!window.has_value()) {
    std::fprintf(stderr, "%s\n", window.error().diagnostic.c_str());
    return 1;
  }
  if (!sessions.has_value()) {
    std::fprintf(stderr, "%s\n", sessions.error().diagnostic.c_str());
    return 1;
  }
  if (made->name() != "work" || sessions->size() != 2 || window->name() != "main" ||
      window->session_id() != made->id()) {
    std::fputs("created session or first window does not match\n", stderr);
    return 1;
  }
  std::puts("Created work with the main window; two sessions are available.");
  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:

Created work with the main window; two sessions are available.

Members7#

environment: std::vector<std::pair<std::string, std::string>> attribute Variables the new process starts with, on top of what tmux passes down.
first_window_name: std::string attribute The name of the window the session starts with.
height: std::optional<int> attribute
name: std::string attribute
shell_command: std::string attribute
start_directory: std::string attribute
width: std::optional<int> attribute The size tmux gives the session while no client is attached.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

NewSessionOptions

Description#

Examples#

Members7#