# control.ControlSender.subscribe

- **Module:** control.ControlSender
- **Package:** libtmux
- **Language:** Rust
- **Kind:** method
- **Source:** https://github.com/libtmux/libtmux-rs/blob/8a648c0894dfffc9303583f753b6c8ae01f2fe76/crates/libtmux/src/control.rs#L849
- **Page:** https://libtmux.org/reference/rs/control-controlsender-subscribe/

```
control.ControlSender.subscribe(self, name: &str, watching: &Subscription, format: &str) -> Result<(), Error>
```

Ask tmux to report a format whenever it changes.

tmux answers with [`Event::SubscriptionChanged`] carrying the name given
here, so one connection can hold several subscriptions and tell them
apart. Reporting is coalesced to at most once a second, so this says
what a value became and not every step it took getting there.

A name already in use is replaced rather than added to.

# Errors

Returns an error when the connection has closed, tmux refuses the
subscription, or the name is empty or contains a colon.

## Example

```rust
use libtmux::control::{ControlMode, Event, Subscription};

let guard = libtmux::test::TestServer::new().await?;
let session = guard.server().new_session("watched").await?;
let (commands, mut events) = ControlMode::attach(guard.server(), session.id())
    .await?
    .split();

commands
    .subscribe("title", &Subscription::Session, "#{session_name}")
    .await?;

// The first report arrives without anything having changed, which is
// what makes a subscription usable for reading the value as well.
while let Some(event) = events.next_event().await {
    if let Event::SubscriptionChanged { name, value, .. } = event {
        assert_eq!(name.as_str()?, "title");
        assert_eq!(value.as_str()?, "watched");
        break;
    }
}

commands.unsubscribe("title").await?;
events.shutdown().await?;
```