Core LibraryAPI Reference

Choose documentation 1

latest

Current version

latest
English

Prerelease This site documents an alpha of libtmux. Its structure, URLs and APIs are subject to change.

typealias libtmux-scala latest

Server

Package io.github.libtmux.scaladsl.Server io.github.libtmux.scaladsl

The Java client, opaque: every member beyond java.lang.AutoCloseable#close is an extension, generated from the operation catalog or handwritten where the catalog marks it WAIT , STREAM or LIFECYCLE . Closing an owned client releases its transport, not tmux; close() comes from the AutoCloseable bound with no forwarding of its own, so Using.resource(server) { ... } works.

View as Markdown

Source and package
Module
io.github.libtmux.scaladsl
Package
io.github.libtmux:libtmux-scala_3
Source
libtmux-scala/src/main/scala/io/github/libtmux/scaladsl/Server.scala
Other languages
PythonRubyLuaTypeScriptRustGoJavaC#C++SwiftKotlin F#
opaque type Server <: AutoCloseable = JavaServerobject Server
typealias [source]

Examples#

Connect to a private tmux server. Use JDK 25, Git, and tmux 3.2a through 3.7c on Linux, with /bin/cat and /bin/sh available. In an empty directory, fetch the documented library revision:

Terminal window
$ git clone https://github.com/libtmux/libtmux-java.git libtmux-source && \
git -C libtmux-source checkout f56392b5d9bc7f1f9c1631842333fb90f3d82d40

Save this consumer setup as settings.gradle.kts: View source

rootProject.name = "api-example"
includeBuild("libtmux-source") {
dependencySubstitution {
substitute(module("io.github.libtmux:libtmux-scala_3"))
.using(project(":libtmux-scala"))
}
}

Save this consumer setup as build.gradle.kts: View source

plugins {
scala
application
}
repositories { mavenCentral() }
dependencies {
implementation("io.github.libtmux:libtmux-scala_3:0.0.1-alpha.17-SNAPSHOT")
implementation("org.scala-lang:scala3-library_3:3.9.0")
}
java { toolchain { languageVersion.set(JavaLanguageVersion.of(25)) } }
application { mainClass.set(providers.gradleProperty("exampleMain")) }

Save this consumer setup as gradle.properties: View source

org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=768m -Dfile.encoding=UTF-8
kotlin.daemon.jvmargs=-Xmx2g
org.gradle.workers.max=2

Save this launcher as run.sh. It creates and stops a private tmux server, including after program failure. A shutdown failure retains its socket directory and exits unsuccessfully. View source

#!/bin/sh
set -eu
if [ "$#" -eq 0 ]; then
printf 'Usage: sh run.sh program [arguments...]\n' >&2
exit 2
fi
binary=$(command -v "${TMUX_BIN:-tmux}")
mkdir -p /tmp/libtmux-java-dev
directory=$(mktemp -d /tmp/libtmux-java-dev/api.XXXXXX)
socket="$directory/tmux.sock"
config="$directory/tmux.conf"
alive() {
"$binary" -S "$socket" display-message -p '#{pid}' >/dev/null 2>&1
}
cleanup() {
status=$?
trap - 0 HUP INT TERM
if alive; then
if ! "$binary" -S "$socket" kill-server; then
printf 'Cannot stop tmux; kept %s\n' "$directory" >&2
exit 1
fi
attempts=0
while alive && [ "$attempts" -lt 100 ]; do
sleep 0.05
attempts=$((attempts + 1))
done
if alive; then
printf 'tmux is still responding; kept %s\n' "$directory" >&2
exit 1
fi
fi
rm -rf "$directory" || exit 1
exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM
unset TMUX TMUX_PANE
printf 'set-option -g default-shell /bin/sh\n' > "$config"
"$binary" -S "$socket" -f "$config" new-session -d -s work-one -n editor /bin/cat
"$binary" -S "$socket" split-window -h -t '=work-one:editor' /bin/cat
"$binary" -S "$socket" new-window -d -t '=work-one' -n logs /bin/cat
"$binary" -S "$socket" new-session -d -s work-two -n editor /bin/cat
"$@" "$binary" "$socket" "$config"
"$binary" -S "$socket" has-session -t '=work-one'
"$binary" -S "$socket" has-session -t '=work-two'

Save this complete program as src/main/scala/Connect.scala. It opens an ordinary client for the launcher's server; closing the client releases its transport. View source

package io.github.libtmux.examples.api.scaladirect
import io.github.libtmux.{ServerConfig, ServerEndpoint}
import java.nio.file.Path
import io.github.libtmux.scaladsl.*
import scala.util.Using
import scala.util.control.NonFatal
/** Connect to a private tmux server. */
object Connect {
def main(args: Array[String]): Unit = {
try {
require(args.length == 3, "expected: tmux-binary socket-path config-file")
val config = ServerConfig
.builder()
.binary(args(0))
.endpoint(ServerEndpoint.socketPath(Path.of(args(1))))
.configFile(Path.of(args(2)))
.build()
Using.resource(Server.open(config)) { server =>
println(s"connected=${server.isAlive()}")
}
} catch {
case NonFatal(error) =>
System.err.println("Example failed: " + error.getMessage)
sys.exit(1)
}
}
}

Build the minimal consumer and run the saved program with the private fixture. An operation or cleanup error makes the command exit unsuccessfully:

Terminal window
$ ./libtmux-source/gradlew --project-dir . --console=plain --quiet \
installDist -PexampleMain=io.github.libtmux.examples.api.scaladirect.Connect && \
sh run.sh build/install/api-example/bin/api-example

Expected output:

connected=true

Discussed in Server, session, window, pane , Commands and control mode · Attaching to tmux , Getting started , Ownership

In other ports A tmux server

Members46 members#

Collections and queries6 members#

  • sessions method The sessions this expression matches, captured now.
  • windows method Captures every winlink, preserving each session and index placement.
  • panes method Captures every pane on the server.
  • clients method Captures every attached client.
  • buffers method The server's paste buffers, which every session shares.
  • snapshot method Captures the whole hierarchy in at most four listings, retrying once if the server is replaced.

Common operations7 members#

  • newSession method Creates a detached session and returns that exact session.
  • killServer method Ends the tmux server and every session on it.
  • cmd method Runs one tmux command against this server.
  • fromJava method Borrows a Java client this facade did not open; closing it closes that client too.
  • hooks method The global hooks every session inherits.
  • open method Opens an owned client for config .
  • shell method Shell commands run by tmux, and tmux commands chosen by a shell exit status.

Other members33 members#

  • admissionBound method How many tmux commands this server's transport runs at once, from ServerConfig#maxConcurrentCommands() for a server #open ed here.
  • asJava method The underlying Java client. Opaque wrapping is free, so this never copies scope or state.
  • attachedSessions method Captures every session a client is attached to.
  • batch method Collects several commands to run in one tmux invocation.
  • chain method Starts a chain of commands where each one acts on what the last one made.
  • channel method One of this server's wait-for channels, which is where a signal is sent and waited for.
  • commands method The commands this tmux knows.
  • config method How this server was configured.
  • control method A control-mode client on session , refused by a tmux other than the one that captured it. LIFECYCLE , handwritten: resource scoping, not a per-operation forward.
  • environment method The server's environment, which every session inherits and every new process is given.
  • expand method Expands a tmux format against the server, and answers with what it came to.
  • given_CanEqual_Server_Server constant
  • globalOptions method The global session options every session inherits unless it sets its own.
  • hasSession method Whether a session with this name exists.
  • identity method Which server this is.
  • isAlive method Whether the server is running and answering.
  • keys method The server's key bindings: prefix when binding, every table when listing.
  • killSession method Ends the session with this name, and everything in it.
  • lock method Locks every client attached to this server.
  • messageLog method The server's message log.
  • options method The server-wide options, the ones tmux keeps once per server.
  • pane method The one pane this expression matches, captured now, or empty when none does.
  • paneFields method Chosen fields for every pane on the server, from one listing.
  • prompt method The command prompt's history.
  • requireAlive method Requires a running tmux daemon that answers the liveness probe.
  • run method Runs a command that is expected to work, and raises when it did not.
  • session method The one session this expression matches, captured now, or empty when none does.
  • sourceFile method Runs a file of tmux commands, as a configuration file would be run.
  • toBuilder method A builder holding every configuration and ownership choice this server made.
  • variables method Reads only validated tmux variable names, never caller-authored format syntax.
  • version method Which tmux this server is running.
  • window method The one window link this expression matches, captured now, or empty when none does.
  • within method This server with every command given timeout rather than the default, sharing this one's transport and scope. LIFECYCLE , handwritten: not a per-operation forward, a derived scope.
Esc

Type to search.