Core LibraryunreleasedAPI Reference

Choose documentation 1

latest

Current version

latest
English

Unreleased io.github.libtmux:libtmux-clojure has not been released. Its API may change during development. This site's structure and URLs may change too.

function libtmux-clojure latest

libtmux.core/open!

Opens local resources for an explicit :socket-path or :socket-name endpoint.

Source and package
Qualified name
libtmux.core/open!
Module
libtmux.core
Declared in
libtmux.core
Package
io.github.libtmux:libtmux-clojure
Source
libtmux-clojure/src/main/clojure/libtmux/core.clj
Other languages
Perlclass Erlangmodule PowerShellcmdlet Juliastruct Elixirstruct Haskell Common Lisp PythonRubyLuaTypeScriptRustGoJavaC#C++SwiftKotlinScalaOCamltypealias F#module

Public owner: libtmux.core

Description#

Supply exactly one endpoint. Paths accept String or java.nio.file.Path. Optional :binary is a command name or path; :config-file is a path; :timeout is a positive java.time.Duration. Unknown keys are rejected. Returns a Server for with-open; closing it does not kill tmux. Use snapshot! to acquire state and close! to release this client.

Examples#

Connect to a private tmux server. Use JDK 25 or newer, the Clojure CLI, Git and tmux on Linux or macOS, with /bin/cat and /bin/sh available. These packages are unpublished. In an empty directory, install this exact source into the consumer's isolated Maven repository:

Terminal window
$ git clone https://github.com/libtmux/libtmux-java libtmux-source && \
git -C libtmux-source checkout --detach 5f88402151ff08fc0390dd438b90963692ec3fe4 && \
(cd libtmux-source && ./gradlew \
:libtmux:publishToMavenLocal \
:libtmux-clojure:publishToMavenLocal \
--console=plain \
"-Dmaven.repo.local=$PWD/../m2")

Save this file as deps.edn. Dependencies resolve from the isolated m2 directory; the core.async dependency is only enabled by its alias. View source

{:paths ["src/main/clojure"]
:mvn/local-repo "m2"
:deps {org.clojure/clojure {:mvn/version "1.12.6"}
io.github.libtmux/libtmux-clojure {:mvn/version "0.1.2-SNAPSHOT"}}
:aliases
{:core-async
{:extra-deps
{io.github.libtmux/libtmux-clojure-core-async {:mvn/version "0.1.2-SNAPSHOT"}}}}}

Save this file as run.sh. The launcher creates and stops a private server, including after program failure, and reports leaked servers as errors. 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 the complete program as src/main/clojure/libtmux/examples/api/connect.clj, creating its parent directories. Closing its client leaves the launcher's server running. View source

(ns libtmux.examples.api.connect
"Connect to the private server supplied by run.sh."
(:require [libtmux.core :as tm]))
(defn -main [& args]
(when-not (= 3 (count args))
(throw (IllegalArgumentException. "expected: tmux-binary socket-path config-file")))
(let [[binary socket config] args]
(with-open [server (tm/open! {:binary binary :socket-path socket
:config-file config})]
(let [snapshot (tm/snapshot! server)]
(assert (seq (:tmux/sessions snapshot)))
(println "connected=true")))))

Run it with the private fixture. Set TMUX_BIN to select another tmux binary:

Terminal window
$ sh run.sh clojure \
-J-Dclojure.main.report=stderr \
-M \
-m libtmux.examples.api.connect

Expected output:

connected=true
Parameters

Guides#

Pages that discuss open!.

In other ports#

A tmux server

Equivalents of A tmux server in other languages
Language Equivalent
Python libtmux.Server
Ruby LibTmux::Server
Lua libtmux.Server
PowerShell LibTmux\New-TmuxServer This cmdlet constructs a shared .NET LibTmux.Server handle without contacting tmux.
Julia LibTmux.Server Server describes an endpoint without contacting tmux. Read its hierarchy with snapshot.
Erlang tmux_server open/1 observes an existing daemon and starts an endpoint owner. Domain rows remain immutable values.
Elixir LibTmux.Server Server describes an existing server by executable and socket. It neither connects nor reserves the server’s identity.
Haskell No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
TypeScript server.Server
Rust server.Server
Go tmux.Server
Java io.github.libtmux.Server
Kotlin io.github.libtmux.kotlin.Server
Scala io.github.libtmux.scaladsl.Server
C# LibTmux.Server
F# LibTmux.FSharp.Server This F# module provides functions over the shared .NET LibTmux.Server type.
C++ libtmux::Server
Swift Server
OCaml Libtmux_unix.Client.t A client is a live, generation-bound server connection. Endpoint describes a socket without connecting; closing a client releases its resources.
Perl LibTmux::Server Construction records connection settings without tmux I/O. Optional LibTmux::Async::Server returns standard Future results for operations.

No equivalent is recorded in Common Lisp.

Esc

Type to search.

Reference previewOpen reference