Tmux – Difference Between ‘off’ and ‘external’ for ‘set-clipboard’ Option

tmux

From man tmux:

set-clipboard [on | external | off]

        Attempt to set the terminal clipboard content using the xterm(1)
        escape sequence, if there is an Ms entry in the terminfo(5)
        description (see the TERMINFO EXTENSIONS section).

        If set to on, tmux will both accept the escape sequence to create
        a buffer and attempt to set the terminal clipboard.  If set to
        external, tmux will attempt to set the terminal clipboard but
        ignore attempts by applications to set tmux buffers.  If off,
        tmux will neither accept the clipboard escape sequence nor
        attempt to set the clipboard.

        Note that this feature needs to be enabled in xterm(1) by setting
        the resource:

              disallowedWindowOps: 20,21,SetXprop

        Or changing this property from the xterm(1) interactive menu when
        required.

This is how I understand the documentation; when Tmux receives a sequence encoded using the Ms capability of the outer terminal:

  • if set-clipboard is set to on, the sequence is used to set the terminal clipboard and a Tmux buffer

  • if set-clipboard is set to off, the sequence is neither used to set the terminal clipboard nor a Tmux buffer

  • if set-clipboard is set to external, the sequence is used to set the terminal clipboard but not a Tmux buffer

I'm using XTerm (patch 322), with $TERM set to xterm-256color, and here is its terminfo description as reported by $ infocmp -1x xterm-256color. In particular, its Ms capability is set like this:

Ms=\E]52;%p1%s;%p2%s\007

I only have these 3 lines inside ~/.Xresources:

XTerm*termName: xterm-256color
XTerm*disallowedWindowOps: 20,21,SetXprop
XTerm*selectToClipboard: true

I start Tmux with no config:

$ tmux -Lx -f/dev/null

I set set-clipboard to on:

$ tmux set -s set-clipboard on

I send an OSC 52 sequence to Tmux via printf containing the text test on:

$ printf '\e]52;c;%s\007' $(printf 'test on' | base64)

The result is that Tmux created an internal buffer, and sent the OSC 52 sequence to XTerm which populated its clipboard with test on:

$ tmux lsb
buffer0: 7 bytes: "test on"

$ xsel -b
test on

Now I reset set-clipboard to off:

$ tmux set -s set-clipboard off

I send an OSC 52 sequence to Tmux via printf containing the text test off:

$ printf '\e]52;c;%s\007' $(printf 'test off' | base64)

This time, Tmux did not create a new internal buffer, and did not send the OSC 52 sequence to XTerm:

$ xsel -b
test on

$ tmux lsb
buffer0: 7 bytes: "test on"

Otherwise one of the output of these 2 shell commands would include test off.


Finally, I reset set-clipboard to external:

$ tmux set -s set-clipboard external

I send an OSC 52 sequence to Tmux via printf containing the text test external:

$ printf '\e]52;c;%s\007' $(printf 'test external' | base64)

Tmux did not create a new internal buffer, and did not send the OSC 52 sequence to XTerm:

$ xsel -b
test on

$ tmux lsb
buffer0: 7 bytes: "test on"

Otherwise one of the output of these 2 shell commands would include test external.


I understand the results when I set set-clipboard to on and to off, but I don't understand the result when I set it to external. Based on this sentence of the Tmux man page:

If set to external, tmux will attempt to set the terminal clipboard but
ignore attempts by applications to set tmux buffers.

I would have expected Tmux to send the OSC 52 sequence to XTerm, without creating an internal buffer.
In practice, it does not create an internal buffer (expected), but does not send the OSC 52 sequence to XTerm either (unexpected).

I must have misunderstood this sentence. Which experiment could I perform to observe a difference between the values external and off?

Best Answer

No, you are not quite correct. There are two actions controlled by this option:

1) Does tmux set the X clipboard with OSC 52 (or whatever is in Ms)?

2) Are applications inside tmux allowed to use OSC 52 to create tmux buffers?

So the three set-clipboard option values mean:

  • off: 1 and 2 are both no;
  • external: 1 is yes, but 2 is no (this is the default);
  • on: both 1 and 2 are yes.

Copying text with copy mode always creates a tmux buffer, set-clipboard makes no difference to this. There are threee ways to create a tmux buffer:

  • Copying text in copy mode (send -X copy-selection/copy-pipe/etc): always creates a tmux buffer; sets the X clipboard if set-clipboard is not off;
  • set-buffer/load-buffer: always create a tmux buffer; never set the X clipboard;
  • OSC 52 from an application inside tmux: creates a tmux buffer and sets the X clipboard, but only if set-clipboard is set to on.
Related Question