Java API

method libtmux-java latest

Server.sessions

The sessions this expression matches, captured now.

Source and package

Qualified name: io.github.libtmux.Server.sessions
Package: io.github.libtmux
Declared in: Server
Distribution: io.github.libtmux:libtmux
Source: libtmux/src/main/java/io/github/libtmux/Server.java
Other languages: Perlmethod Erlangfunction PowerShellcmdlet Juliafunction Elixirfunction Haskell Common Lispfunction PythonRubyLuaTypeScriptRustGoC#C++SwiftKotlinScalaOCamlfunction F#function Clojurefunction

@ReadOnly @Operation(Kind.READ) public List<Session> sessions( FilterExpr<Session> expression)@ReadOnly @Operation(Kind.READ) public List<Session> sessions() method overload 2 overloads [source] ¶

Description#

A safe expression is sent as list-sessions -f. The sessions that come back are still tested with the expression. A relation, or an expression tmux cannot apply, reads the whole server and filters that capture; a filtered read that finds nothing is the answer.

Examples#

List the sessions returned by a server read. Use JDK 25, Gradle 9 or newer, and tmux 3.3a or newer on Linux, with /bin/cat and /bin/sh available. In an empty directory, save this consumer setup as settings.gradle.kts:

rootProject.name = "api-example"

Save this consumer setup as build.gradle.kts. It depends on the 0.1.2 release from Maven Central:

plugins {
    application
}

repositories { mavenCentral() }

dependencies {
    implementation("io.github.libtmux:libtmux:0.1.2")
}

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}")
root=${API_RUN_ROOT:-/tmp/libtmux-java-dev}

# A client that names no socket follows TMUX or LIBTMUX_SOCKET*, and otherwise lands on the default
# socket under TMUX_TMPDIR. The program gets none of them, and a TMUX_TMPDIR of its own below.
unset TMUX TMUX_PANE
for name in $(env | sed -n 's/^\(LIBTMUX_SOCKET[A-Za-z0-9_]*\)=.*/\1/p'); do
    unset "$name"
done

mkdir -p "$root"
directory=$(mktemp -d "$root/api.XXXXXX")
tmpdir=$(mktemp -d "$root/tmpdir.XXXXXX")
socket="$directory/tmux.sock"
config="$directory/tmux.conf"

serves() {
    "$binary" -S "$1" display-message -p '#{pid}' >/dev/null 2>&1
}

# Stops the server on the socket, then waits for it to stop answering.
stop() {
    "$binary" -S "$1" kill-server || return 1
    attempts=0
    while serves "$1" && [ "$attempts" -lt 60 ]; do
        sleep 0.05
        attempts=$((attempts + 1))
    done
    ! serves "$1"
}

cleanup() {
    status=$?
    trap - 0 HUP INT TERM PIPE
    # A closed output must not end the cleanup, whose messages are the only thing left to write.
    trap '' PIPE
    set +e
    stuck=
    left=
    if [ -S "$socket" ] && serves "$socket" && ! stop "$socket"; then
        stuck="$stuck tmux.sock"
    fi
    # Every socket anywhere under either directory, without following links. Only one a server answers
    # on is a leak; the runner's own is expected to be there.
    old_ifs=$IFS
    IFS='
'
    set -f
    for candidate in $(find "$tmpdir" "$directory" -type s 2>/dev/null); do
        [ "$candidate" = "$socket" ] && continue
        serves "$candidate" || continue
        case "$candidate" in
            "$tmpdir"/*) name=${candidate#"$tmpdir"/} ;;
            *) name=${candidate#"$directory"/} ;;
        esac
        left="$left $name"
        stop "$candidate" || stuck="$stuck $name"
    done
    set +f
    IFS=$old_ifs
    if [ -n "$stuck" ]; then
        printf 'tmux still answers on%s after kill-server; kept %s and %s under the runner root\n' \
            "$stuck" "${directory##*/}" "${tmpdir##*/}" >&2
        exit 1
    fi
    rm -rf "$directory" "$tmpdir" || exit 1
    if [ -n "$left" ]; then
        printf 'The program left a tmux server running:%s\n' "$left" >&2
        exit 1
    fi
    exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM PIPE

# A default socket path longer than this does not fit in sun_path.
default_socket="$tmpdir/tmux-$(id -u)/default"
if [ "$(printf '%s' "$default_socket" | wc -c)" -gt 100 ]; then
    printf 'API_RUN_ROOT is too long for a tmux socket\n' >&2
    exit 1
fi
TMUX_TMPDIR=$tmpdir
export TMUX_TMPDIR

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/java/ListSessions.java. It opens an ordinary client for the launcher's server; closing the client releases its transport. View source

package io.github.libtmux.examples.api.java;

import io.github.libtmux.Server;
import io.github.libtmux.ServerConfig;
import io.github.libtmux.ServerEndpoint;
import java.nio.file.Path;
import java.util.stream.Collectors;

/** List the sessions returned by a server read. */
public final class ListSessions {
    private ListSessions() {}

    public static void main(String[] args) {
        try {
            if (args.length != 3) {
                throw new IllegalArgumentException("expected: tmux-binary socket-path config-file");
            }
            var config = ServerConfig.builder()
                    .binary(args[0])
                    .endpoint(ServerEndpoint.socketPath(Path.of(args[1])))
                    .configFile(Path.of(args[2]))
                    .build();
            try (Server server = Server.open(config)) {
                System.out.println("sessions="
                        + server.sessions().stream()
                                .map(session -> session.name())
                                .sorted()
                                .collect(Collectors.joining(",")));
            }
        } catch (Exception error) {
            if (error instanceof InterruptedException) Thread.currentThread().interrupt();
            System.err.println("Example failed: " + error.getMessage());
            System.exit(1);
        }
    }
}

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

$ gradle --console=plain --quiet installDist -PexampleMain=io.github.libtmux.examples.api.java.ListSessions && \
  sh run.sh build/install/api-example/bin/api-example

Expected output:

sessions=work-one,work-two

Select sessions with a typed name filter. Use JDK 25, Gradle 9 or newer, and tmux 3.3a or newer on Linux, with /bin/cat and /bin/sh available. In an empty directory, save this consumer setup as settings.gradle.kts:

rootProject.name = "api-example"

Save this consumer setup as build.gradle.kts. It depends on the 0.1.2 release from Maven Central:

plugins {
    application
}

repositories { mavenCentral() }

dependencies {
    implementation("io.github.libtmux:libtmux:0.1.2")
}

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}")
root=${API_RUN_ROOT:-/tmp/libtmux-java-dev}

# A client that names no socket follows TMUX or LIBTMUX_SOCKET*, and otherwise lands on the default
# socket under TMUX_TMPDIR. The program gets none of them, and a TMUX_TMPDIR of its own below.
unset TMUX TMUX_PANE
for name in $(env | sed -n 's/^\(LIBTMUX_SOCKET[A-Za-z0-9_]*\)=.*/\1/p'); do
    unset "$name"
done

mkdir -p "$root"
directory=$(mktemp -d "$root/api.XXXXXX")
tmpdir=$(mktemp -d "$root/tmpdir.XXXXXX")
socket="$directory/tmux.sock"
config="$directory/tmux.conf"

serves() {
    "$binary" -S "$1" display-message -p '#{pid}' >/dev/null 2>&1
}

# Stops the server on the socket, then waits for it to stop answering.
stop() {
    "$binary" -S "$1" kill-server || return 1
    attempts=0
    while serves "$1" && [ "$attempts" -lt 60 ]; do
        sleep 0.05
        attempts=$((attempts + 1))
    done
    ! serves "$1"
}

cleanup() {
    status=$?
    trap - 0 HUP INT TERM PIPE
    # A closed output must not end the cleanup, whose messages are the only thing left to write.
    trap '' PIPE
    set +e
    stuck=
    left=
    if [ -S "$socket" ] && serves "$socket" && ! stop "$socket"; then
        stuck="$stuck tmux.sock"
    fi
    # Every socket anywhere under either directory, without following links. Only one a server answers
    # on is a leak; the runner's own is expected to be there.
    old_ifs=$IFS
    IFS='
'
    set -f
    for candidate in $(find "$tmpdir" "$directory" -type s 2>/dev/null); do
        [ "$candidate" = "$socket" ] && continue
        serves "$candidate" || continue
        case "$candidate" in
            "$tmpdir"/*) name=${candidate#"$tmpdir"/} ;;
            *) name=${candidate#"$directory"/} ;;
        esac
        left="$left $name"
        stop "$candidate" || stuck="$stuck $name"
    done
    set +f
    IFS=$old_ifs
    if [ -n "$stuck" ]; then
        printf 'tmux still answers on%s after kill-server; kept %s and %s under the runner root\n' \
            "$stuck" "${directory##*/}" "${tmpdir##*/}" >&2
        exit 1
    fi
    rm -rf "$directory" "$tmpdir" || exit 1
    if [ -n "$left" ]; then
        printf 'The program left a tmux server running:%s\n' "$left" >&2
        exit 1
    fi
    exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM PIPE

# A default socket path longer than this does not fit in sun_path.
default_socket="$tmpdir/tmux-$(id -u)/default"
if [ "$(printf '%s' "$default_socket" | wc -c)" -gt 100 ]; then
    printf 'API_RUN_ROOT is too long for a tmux socket\n' >&2
    exit 1
fi
TMUX_TMPDIR=$tmpdir
export TMUX_TMPDIR

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/java/Query.java. It opens an ordinary client for the launcher's server; closing the client releases its transport. View source

package io.github.libtmux.examples.api.java;

import io.github.libtmux.Server;
import io.github.libtmux.ServerConfig;
import io.github.libtmux.ServerEndpoint;
import io.github.libtmux.Session_;
import java.nio.file.Path;
import java.util.stream.Collectors;

/** Select sessions with a typed name filter. */
public final class Query {
    private Query() {}

    public static void main(String[] args) {
        try {
            if (args.length != 3) {
                throw new IllegalArgumentException("expected: tmux-binary socket-path config-file");
            }
            var config = ServerConfig.builder()
                    .binary(args[0])
                    .endpoint(ServerEndpoint.socketPath(Path.of(args[1])))
                    .configFile(Path.of(args[2]))
                    .build();
            try (Server server = Server.open(config)) {
                var matches = server.sessions(Session_.name().is("work-one"));
                System.out.println("matches="
                        + matches.stream()
                                .map(session -> session.name())
                                .sorted()
                                .collect(Collectors.joining(",")));
            }
        } catch (Exception error) {
            if (error instanceof InterruptedException) Thread.currentThread().interrupt();
            System.err.println("Example failed: " + error.getMessage());
            System.exit(1);
        }
    }
}

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

$ gradle --console=plain --quiet installDist -PexampleMain=io.github.libtmux.examples.api.java.Query && \
  sh run.sh build/install/api-example/bin/api-example

Expected output:

matches=work-one

Parameters

expression (FilterExpr<Session>) # for sessions(expression)

Returns

an immutable list in tmux order for sessions(expression)

Raises

ServerUnavailableException – if no daemon is running
LibTmuxException – if the capture otherwise fails

tmux command#

The tmux commands behind sessions.

list-sessions

tmux C API#

The C declarations in tmux that implement these commands.

cmd_list_sessions_entry cmd_list_sessions_exec

Guides#

Pages that discuss sessions.

Guides: Querying and filtering
Topics: Traversal

In other ports#

List the server’s sessions

Equivalents of List the server’s sessions in other languages
Language	Equivalent
Python	`libtmux.Server.sessions`
Ruby	`LibTmux::Server#list_sessions`
Lua	`libtmux.Snapshot.sessions`
PowerShell	`LibTmux\Get-TmuxSession` Acquires sessions through `-Server`, with optional exact `-Id` and `-Name` selectors.
Julia	`LibTmux.sessions` `sessions` reads membership from a captured `Snapshot` without contacting tmux.
Erlang	`tmux_snapshot:sessions/1` Returns captured rows without tmux I/O.
Elixir	`LibTmux.Snapshot.sessions/1` Returns a `Selection` of captured sessions without contacting tmux.
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
Common Lisp	`libtmux:sessions` `sessions` returns a fresh vector from a captured snapshot without contacting tmux.
TypeScript	`server.Server.sessions`
Rust	`server.Server.sessions`
Go	`tmux.Server.Sessions`
Clojure	`libtmux.core/sessions!` Acquires a new captured graph and returns its session maps; acquisition failure throws.
Kotlin	`io.github.libtmux.kotlin.Server.sessions`
Scala	`io.github.libtmux.scaladsl.Server.sessions`
C#	`LibTmux.Server.Sessions`
F#	`LibTmux.FSharp.Server.sessions` Builds a deferred session query on `LibTmux.Server`. `Query.list` acquires the results; it does not traverse the handle’s captured membership.
C++	`libtmux::Server::sessions`
Swift	`Server.sessions()`
OCaml	`Libtmux.Snapshot.sessions` Reads an immutable array of already captured sessions without I/O.
Perl	`LibTmux::Snapshot::sessions` Reads captured membership locally, preserving order.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Server.sessions

Description#

Examples#

tmux command#

tmux C API#

Guides#

In other ports#

Description#

Examples#

tmux command#

tmux C API#

Guides#

In other ports#

Related types#