Server.new_session
Created detached, and returned, because tmux prints what it made.
Source and package
- [[
C++ nodiscard attributeAsks the compiler to warn when a result is discarded. An explicit cast to void acknowledges that the result is intentionally ignored.]] expected<Session, CommandFailure > new_session(std::string name) const;[[_view C++ nodiscard attributeAsks the compiler to warn when a result is discarded. An explicit cast to void acknowledges that the result is intentionally ignored.]] expected<Session, CommandFailure > new_session(NewSession options) const;Options -
Description#
Windows psmux rejects typed creation: concurrent creators cannot prove ownership.
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:
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;}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:
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:
Created work with the main window; two sessions are available.- Parameters
-
-
name(std::string ) # for_view new_session(name) -
options(NewSession ) # forOptions new_session(options)
-
tmux command#
The tmux commands behind new_session.
tmux C API#
The C declarations in tmux that implement these commands.
Each path starts at a function a command runs, which is degree 1. The degree counts steps from there along the path, and each step is a call or a reference: degree 2 is reached from that function, degree 3 from the next, and so on.
Create a session and its first pane
- 1
cmd_new_session_exec - calls → 2
spawn_window - calls → 3
spawn_pane - calls → 4
window_add_pane - calls → 5
window_pane_create
In other ports#
Create a session
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| Lua | libtmux |
| Erlang | tmux |
| 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 |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| Swift | Server |
| OCaml | Libtmux |
| Perl | Lib Explicit Server operation. Captured entities remain local observations; use a new snapshot to observe changes. |
No equivalent is recorded in PowerShell, Julia, Elixir, Common Lisp or F#.