# Socket and servers

Source: https://libtmux.org/en/tmux/topics/socket-and-servers/

> Select a server socket, check liveness, and detect a replacement daemon.

A tmux server is selected by its Unix-domain socket. Use different sockets for
independent servers, such as a development session and an isolated test server.
Choose the default socket, a named socket (`-L`), or an explicit path (`-S`).

## Naming a server

### Python
[`Server()`](<https://libtmux.org/en/py/latest/reference/libtmux-server/>) selects the default socket. Pass `socket_name="work"` to
select a named socket, or `socket_path="/tmp/tmux-1000/work"` for an
explicit path.

### TypeScript
`new Server()` selects the default socket. Set `socketName` to select
a named socket, or `socketPath` to use an explicit path.

### Go
[`tmux.NewServer(tmux.ServerOptions{})`](<https://libtmux.org/en/go/latest/reference/tmux-newserver/>) selects the default socket.
Set [`ServerOptions.SocketName`](<https://libtmux.org/en/go/latest/reference/tmux-serveroptions-socketname/>) for a named socket or
[`ServerOptions.SocketPath`](<https://libtmux.org/en/go/latest/reference/tmux-serveroptions-socketpath/>) for an explicit path.

### Rust
[`Server::new()`](<https://libtmux.org/en/rs/latest/reference/server-server-new/>) selects the default socket. Use
[`Server::builder().socket_name("work").build()?`](<https://libtmux.org/en/rs/latest/reference/server-server-builder/>) for a named socket or
[`Server::builder().socket_path(path).build()?`](<https://libtmux.org/en/rs/latest/reference/server-server-builder/>) for an explicit path.

### Java
[`ServerEndpoint.defaultSocket()`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-serverendpoint-serverendpoint-defaultsocket/>) selects the default socket.
[`ServerEndpoint.namedSocket("work")`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-serverendpoint-serverendpoint-namedsocket-uymy/>) selects a named socket, and
[`ServerEndpoint.socketPath(path)`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-serverendpoint-serverendpoint-socketpath-l4dk/>) selects an explicit path.

### C#
`new ServerConnectionOptions()` selects the default socket. Supply
`socketName` for a named socket or `socketPath` for an explicit path.

### C++
[`Server::at_default()`](<https://libtmux.org/en/cxx/latest/reference/libtmux-server-at_default/>) selects the default socket. Use
[`Server::at_socket_name("work")`](<https://libtmux.org/en/cxx/latest/reference/libtmux-server-at_socket_name/>) for a named socket or
[`Server::at_socket_path(path)`](<https://libtmux.org/en/cxx/latest/reference/libtmux-server-at_socket_path/>) for an explicit path.

### Swift
Select a named socket with [`Server(socketName: "work")`](<https://libtmux.org/en/swift/latest/reference/server/>) or an
explicit path with [`Server(socketPath: path)`](<https://libtmux.org/en/swift/latest/reference/server/>). The initializer requires
a socket selection; see the default-socket example below.

```python
default_server = libtmux.Server()
named = libtmux.Server(socket_name="work")
```

```typescript
const named = new Server({ socketName: "work" });
```

```go
named, err := tmux.NewServer(tmux.ServerOptions{SocketName: "work"})
if err != nil {
    return err
}
```

```rust
let named = libtmux::Server::builder().socket_name("work").build()?;
```

```java
ServerConfig config = ServerConfig.builder()
        .endpoint(ServerEndpoint.namedSocket("work"))
        .build();
Server named = Server.open(config);
```

```csharp
using LibTmux;

Server named = await Server.ConnectAsync(new ServerConnectionOptions(socketName: "work"));
```

```cpp
auto named = libtmux::Server::at_socket_name("work");
```

```swift
let named = try Server(socketName: "work")
```

Choose either a socket name or a socket path. tmux uses `TMUX_TMPDIR` to
resolve the directory for default and named sockets.

Supplying both selectors raises [`TypeError`](<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError>).
[`ServerOptions.SocketPath`](<https://libtmux.org/en/go/latest/reference/tmux-serveroptions-socketpath/>) takes precedence over [`ServerOptions.SocketName`](<https://libtmux.org/en/go/latest/reference/tmux-serveroptions-socketname/>) when both are set.

Swift requires an explicit `socketPath` or [`socketName`](<https://libtmux.org/en/swift/latest/reference/endpoint-socketname(_-)/>) argument. To reach
tmux's default socket, use [`Server(socketName: "default")`](<https://libtmux.org/en/swift/latest/reference/server/>).

[`Server(socket_name_factory=...)`](<https://libtmux.org/en/py/latest/reference/libtmux-server/>) accepts a callable that generates socket
names. Use a unique name for each isolated test server.
[`ServerConnectionOptions(socketNameFactory: ...)`](<https://libtmux.org/en/csharp/latest/reference/libtmux-serverconnectionoptions/>) accepts a callable that
generates socket names. Use a unique name for each isolated test server.

## Is the server actually there?

A server handle does not prove that the target server is running. Use a liveness
check when your program needs to distinguish a live server from an unavailable
socket:

### Python
[`Server.is_alive`](<https://libtmux.org/en/py/latest/reference/libtmux-server-is_alive/>) returns a boolean indicating whether the server
responds.

### TypeScript
[`Server.isAlive`](<https://libtmux.org/en/ts/latest/reference/server-server-isalive/>) returns a promise of a boolean. [`Server.raiseIfDead`](<https://libtmux.org/en/ts/latest/reference/server-server-raiseifdead/>)
throws when the server is unavailable and retains the reason reported by tmux.

### Go
[`Server.IsAlive`](<https://libtmux.org/en/go/latest/reference/tmux-server-isalive/>) returns `(bool, error)`. The error reports a check
that could not be completed; a false result alone means the server is not alive.

### Rust
[`Server.is_alive`](<https://libtmux.org/en/rs/latest/reference/server-server-is_alive/>) returns a boolean. Use [`Server.check_alive`](<https://libtmux.org/en/rs/latest/reference/server-server-check_alive/>) when
you also need to distinguish a failed check from a server that is not alive.

### Java
[`Server.isAlive`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-server-server-isalive/>) returns a boolean.

### C#
[`Server.IsAliveAsync`](<https://libtmux.org/en/csharp/latest/reference/libtmux-server-isaliveasync/>) returns `Task<bool>`.

### C++
[`Server.is_alive`](<https://libtmux.org/en/cxx/latest/reference/libtmux-server-is_alive/>) takes a timeout and returns a boolean.

### Swift
[`Server.isRunning`](<https://libtmux.org/en/swift/latest/reference/server-isrunning()/>) is an async throwing check that returns [`Bool`](<https://developer.apple.com/documentation/swift/bool>).

```python
if server.is_alive():
    server.sessions
```

```typescript
if (await server.isAlive()) {
  await server.snapshot();
}
```

```go
alive, err := server.IsAlive(ctx)
if err != nil {
    return err
}
fmt.Println("server running:", alive)
```

```rust
if server.is_alive().await {
    server.sessions().await?;
}
```

```java
if (server.isAlive()) {
    server.sessions();
}
```

```csharp
if (await server.IsAliveAsync())
{
    await server.GetSessionsAsync();
}
```

```cpp
if (server.is_alive(std::chrono::seconds{2})) {
  server.sessions();
}
```

```swift
if try await server.isRunning() {
    try await server.sessions()
}
```

[`isAlive()`](<https://libtmux.org/en/ts/latest/reference/server-server-isalive/>) returns a boolean. Use [`raiseIfDead()`](<https://libtmux.org/en/ts/latest/reference/server-server-raiseifdead/>) when you need failure details.
[`is_alive()`](<https://libtmux.org/en/rs/latest/reference/server-server-is_alive/>) returns a boolean. Use [`check_alive()`](<https://libtmux.org/en/rs/latest/reference/server-server-check_alive/>) when you need failure details.

## Killing a server, and telling two apart

Killing a server ends all its sessions. Use this only for a server your program
owns; for narrower cleanup, kill the session or pane you created.

Call [`server.kill_server()`](<https://libtmux.org/en/py/latest/reference/libtmux-server-kill_server/>). [`Server.__eq__`](<https://libtmux.org/en/py/latest/reference/libtmux-server-__eq__/>) compares [`socket_name`](<https://libtmux.org/en/py/latest/reference/libtmux-server-socket_name/>) and
`socket_path` when deciding whether two handles select the same endpoint.
Call [`await server.kill()`](<https://libtmux.org/en/ts/latest/reference/server-server-kill/>). [`TmuxServerRestartedError`](<https://libtmux.org/en/ts/latest/reference/errors-tmuxserverrestartederror/>) reports an operation
whose handle encountered a replacement daemon on the same socket.
Call [`server.Kill(ctx)`](<https://libtmux.org/en/go/latest/reference/tmux-server-kill/>) and check its error. [`server.Equal(other)`](<https://libtmux.org/en/go/latest/reference/tmux-server-equal/>) compares
the captured socket bindings, resolving relative paths and environment-based
socket names. Equal endpoints do not prove equal daemon lifetimes.
[`ErrDaemonReplaced`](<https://libtmux.org/en/go/latest/reference/tmux-errdaemonreplaced/>) reports a replacement daemon on the selected socket.
Call [`server.kill().await?`](<https://libtmux.org/en/rs/latest/reference/server-server-kill/>) and handle a cleanup failure before returning.
Call [`server.killServer()`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-server-server-killserver/>) to stop tmux. [`Server.close()`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-server-server-close/>) releases the local
connection and leaves tmux running; see [Ownership and cleanup](https://libtmux.org/en/tmux/topics/context-managers/).
Call [`await server.KillAsync()`](<https://libtmux.org/en/csharp/latest/reference/libtmux-server-killasync/>) and handle a cleanup failure before returning.
Call [`server.kill()`](<https://libtmux.org/en/cxx/latest/reference/libtmux-server-kill/>) and inspect its result for a failure.
Call [`try await server.killServer()`](<https://libtmux.org/en/swift/latest/reference/server-killserver()/>) and handle a cleanup failure before returning.

A restarted server can reuse a socket path while having different state. Do
not treat a matching path as proof that a cached object still exists.