Session.windows
List the windows linked into this session, preserving any failure.
Source and package
- Qualified name
-
libtmux::session:: Session:: windows - Module
- session
- Declared in
Session- Package
- libtmux
- Source
- crates/libtmux/src/session.rs
- Other languages
- Perl Erlangfunction PowerShellcmdlet Juliafunction Elixir Haskell Common Lispfunction PythonRuby Lua TypeScriptGoJavaC#C++SwiftKotlinScalaOCamlfunction F#function Clojurefunction
-
Description#
A window linked into other sessions appears here once, under this session's own index for it.
Errors
Returns an error when the list command cannot run, or when its output cannot be decoded into snapshots.
Examples#
List sessions, windows and panes. Read each collection and its relations, then inspect a hierarchy snapshot. Use Rust 1.85 or newer with Cargo, and tmux 3.3a or newer, on a Unix system. In an empty directory, create a project and add the published crates:
Terminal window $ cargo init --name libtmux-api-example &&cargo add libtmux@0.1.2 tempfile@3.20 &&cargo add tokio@1.40 --features macros,rt,timeReplace
src/main.rswith this complete program. It owns a private tmux socket, applies a ten-second task deadline, and reports both task and cleanup errors.Server::kill()stops its daemon;Server::shutdown()closes its client executor. Successful cleanup removes the temporary directory even when the task fails. View source//! List sessions, windows and panes, then read their hierarchy.use std::error::Error;use std::time::Duration;use libtmux::{NewSessionOptions, NewWindowOptions, Server};type ExampleError = Box<dyn Error>;fn check(condition: bool, message: &str) -> Result<(), ExampleError> {if condition {Ok(())} else {Err(message.into())}}async fn demonstrate(server: &Server) -> Result<(), ExampleError> {let session = server.new_session(NewSessionOptions::new("work").window_name("editor").command("cat"),).await?;session.new_window(NewWindowOptions::new("logs").command("cat")).await?;let sessions = server.sessions().await?;let windows = server.windows().await?;let panes = server.panes().await?;check(sessions.len() == 1, "expected one session")?;check(windows.len() == 2, "expected two windows")?;check(panes.len() == 2, "expected two panes")?;check(session.windows().await?.len() == 2,"expected two session windows",)?;check(session.panes().await?.len() == 2,"expected two session panes",)?;for window in &windows {check(window.session_id() == session.id(),"window belongs to another session",)?;check(window.panes().await?.len() == 1,"expected one pane per window",)?;}let hierarchy = server.hierarchy().await?;let branch = hierarchy.first().ok_or("hierarchy has no session")?;check(branch.session.id() == session.id(),"hierarchy session differs",)?;check(branch.windows.len() == 2, "expected two hierarchy windows")?;check(branch.windows.iter().all(|window| window.panes.len() == 1),"hierarchy panes differ",)?;println!("listings: 1 session, 2 windows, 2 panes");Ok(())}#[tokio::main(flavor = "current_thread")]async fn main() -> Result<(), ExampleError> {let root = std::path::Path::new("/tmp/libtmux-rs-dev");std::fs::create_dir_all(root)?;let directory = tempfile::Builder::new().prefix("api-listings-").tempdir_in(root)?;std::fs::write(directory.path().join("owner"),std::process::id().to_string(),)?;let server = Server::builder().socket_path(directory.path().join("tmux.sock")).config_file("/dev/null").default_timeout(Duration::from_secs(5)).build()?;let outcome = tokio::time::timeout(Duration::from_secs(10), demonstrate(&server)).await;// Stop the owned daemon before closing the client executor.let killed = server.kill().await;let closed = server.shutdown().await;let cleanup_failed = killed.is_err() || closed.is_err();let mut failures = Vec::new();match outcome {Ok(Ok(())) => {}Ok(Err(error)) => failures.push(format!("example failed: {error}")),Err(error) => failures.push(format!("example deadline: {error}")),}if let Err(error) = killed {failures.push(format!("daemon cleanup: {error}"));}if let Err(error) = closed {failures.push(format!("executor cleanup: {error}"));}if cleanup_failed {let retained = directory.keep();failures.push(format!("inspect retained directory {}", retained.display()));} else if let Err(error) = directory.close() {failures.push(format!("directory cleanup: {error}"));}if failures.is_empty() {Ok(())} else {Err(failures.join("; ").into())}}Run the consumer. Success exits with status 0; setup, operation, deadline or cleanup failures exit unsuccessfully and print diagnostics to stderr:
Terminal window $ cargo run --quietExpected output:
listings: 1 session, 2 windows, 2 panes
tmux command#
The tmux commands behind windows.
list-windows -t session scope, cmd_list_windows_exec tmux C API#
The C declarations in tmux that implement these commands.
Guides#
Pages that discuss windows.
In other ports#
List a session's windows
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| PowerShell | Lib Use the -Session parameter set to acquire placements in one session. |
| Julia | Lib windows with a captured SessionSnapshot reads distinct physical windows in that session. Use windowlinks for placements. |
| Erlang | tmux Pass windows, a captured session and its snapshot for a local relationship read. |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| Common Lisp | libtmux: windows traverses a captured session. Repeated links preserve their physical-window multiplicity. |
| TypeScript | session |
| Go | tmux |
| Java | io |
| Clojure | libtmux Traverses one capture locally. It does not issue a list-windows command. |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| F# | Lib Builds a deferred window query from one LibTmux.Session and its server. Query.list acquires placements scoped to that session ID. |
| C++ | libtmux:: |
| Swift | Snapshot |
| OCaml | Libtmux Reads distinct captured global windows in this session. window_links preserves individual indexed placements. |
| Perl | Traverse Session::window_links and resolve each link’s window, preserving explicit session placement and multiplicity. |
No equivalent is recorded in Lua or Elixir.