[PATCH] [doc] clone module using xterm's slave mode

[PATCH] [doc] clone module using xterm's slave mode

[Stephane Chazelas]

Hi, while testing the patch for the pgrp restore issue, I came
up with a way to clone zsh onto a xterm and attach to the tty
device properly there (using xterm's slave mode).

Here's a doc patch to document that approach (requires socat,
though the same could be done with expect or some perl/python
pty module).

I changed the trap : INT to trap "" INT so the signals are
properly ignored. (trap : INT makes the signal harmless to sh,
but would still kill "sleep" in those sh implementations where
sleep is not builtin).

diff --git a/Doc/Zsh/mod_clone.yo b/Doc/Zsh/mod_clone.yo
index 02dc5be0e..a3801cd40 100644
--- a/Doc/Zsh/mod_clone.yo
+++ b/Doc/Zsh/mod_clone.yo
@@ -20,7 +20,7 @@ and non-zero on error.
 The target of tt(clone) should be an unused terminal, such as an unused virtual
 console or a virtual terminal created by
 
-example(xterm -e sh -c 'trap : INT QUIT TSTP; tty;
+example(xterm -e sh -c 'trap "" INT QUIT TSTP; tty;
         while :; do sleep 100000000; done')
 
 Some words of explanation are warranted about this long xterm command
@@ -39,11 +39,30 @@ enditemize()
 
 This does not apply when cloning to an em(unused) vc.
 
-Cloning to a used (and unprepared) terminal will result in two
-processes reading simultaneously from the same terminal, with
-input bytes going randomly to either process.
+It is possible however to clone zsh onto a xterm and that zsh process
+to lead the session attached to that terminal by using tt(xterm)'s slave
+mode in conjunction with an utility like tt(socat) that can create a
+pseudo-terminal pair:
 
-tt(clone) is mostly useful as a shell built-in replacement for
-openvt.
+example(socat pty,link=pty,wait-slave,echo=0 'exec:xterm -Spty/3,nofork,fdout=3,fdin=3' &
+        clone pty; (($!)) || { IFS= read -r WINDOWID && ((WINDOWID = 0x$WINDOWID));})
+
+Above, tt(socat) creates a pseudo terminal, and makes a tt(pty) symbolic
+link to the slave device in the current directory. As soon as a process
+opens that device, tt(xterm) is started with its file descriptor 3
+connected to the master side.
+
+The cloned zsh is the process that opens that device here. And once
+started, we make it read the X11 Window ID that tt(xterm) oututs there
+into tt($WINDOWID) (the same variable that xterm sets itself when not in
+slave mode) before resuming normal operation. That zsh process becomes
+the session leader attached to the tty device in the same way a zsh
+started with tt(xterm -e zsh) would, and job control works as it should.
+
+Cloning to a used (and unprepared) terminal will result in two processes
+reading simultaneously from the same terminal, with input bytes going
+randomly to either process.
+
+tt(clone) is mostly useful as a shell built-in replacement for openvt.
 )
 enditem()

Re: [PATCH] [doc] clone module using xterm's slave mode

[Mikael Magnusson]

On 5/17/20, Stephane Chazelas <stephane@chazelas.org> wrote:
> Here's a doc patch to document that approach (requires socat,
> though the same could be done with expect or some perl/python
> pty module).
>
> @@ -39,11 +39,30 @@ enditemize()
> +The cloned zsh is the process that opens that device here. And once
> +started, we make it read the X11 Window ID that tt(xterm) oututs there

outputs


-- 
Mikael Magnusson

Re: [PATCHv2] [doc] clone module using xterm's slave mode

[Stephane Chazelas]

2020-05-17 22:19:24 +0200, Mikael Magnusson:
[...]
> > +started, we make it read the X11 Window ID that tt(xterm) oututs there
> 
> outputs
[...]

Sorry about that. v2:

diff --git a/Doc/Zsh/mod_clone.yo b/Doc/Zsh/mod_clone.yo
index 02dc5be0e..634a8b106 100644
--- a/Doc/Zsh/mod_clone.yo
+++ b/Doc/Zsh/mod_clone.yo
@@ -20,7 +20,7 @@ and non-zero on error.
 The target of tt(clone) should be an unused terminal, such as an unused virtual
 console or a virtual terminal created by
 
-example(xterm -e sh -c 'trap : INT QUIT TSTP; tty;
+example(xterm -e sh -c 'trap "" INT QUIT TSTP; tty;
         while :; do sleep 100000000; done')
 
 Some words of explanation are warranted about this long xterm command
@@ -39,11 +39,30 @@ enditemize()
 
 This does not apply when cloning to an em(unused) vc.
 
-Cloning to a used (and unprepared) terminal will result in two
-processes reading simultaneously from the same terminal, with
-input bytes going randomly to either process.
+It is possible however to clone zsh onto a xterm and that zsh process
+to lead the session attached to that terminal by using tt(xterm)'s slave
+mode in conjunction with an utility like tt(socat) that can create a
+pseudo-terminal pair:
 
-tt(clone) is mostly useful as a shell built-in replacement for
-openvt.
+example(socat pty,link=pty,wait-slave,echo=0 'exec:xterm -Spty/3,nofork,fdout=3,fdin=3' &
+        clone pty; (($!)) || { IFS= read -r WINDOWID && ((WINDOWID = 0x$WINDOWID));})
+
+Above, tt(socat) creates a pseudo terminal, and makes a tt(pty) symbolic
+link to the slave device in the current directory. As soon as a process
+opens that device, tt(xterm) is started with its file descriptor 3
+connected to the master side.
+
+The cloned zsh is the process that opens that device here. And once
+started, we make it read the X11 Window ID that tt(xterm) outputs there
+into tt($WINDOWID) (the same variable that xterm sets itself when not in
+slave mode) before resuming normal operation. That zsh process becomes
+the session leader attached to the tty device in the same way a zsh
+started with tt(xterm -e zsh) would, and job control works as it should.
+
+Cloning to a used (and unprepared) terminal will result in two processes
+reading simultaneously from the same terminal, with input bytes going
+randomly to either process.
+
+tt(clone) is mostly useful as a shell built-in replacement for openvt.
 )
 enditem()

Re: [PATCH] [doc] clone module using xterm's slave mode

[Daniel Shahaf]

Stephane Chazelas wrote on Sun, 17 May 2020 11:13 +0100:
> Hi, while testing the patch for the pgrp restore issue, I came
> up with a way to clone zsh onto a xterm and attach to the tty
> device properly there (using xterm's slave mode).
> 
> Here's a doc patch to document that approach (requires socat,
> though the same could be done with expect or some perl/python
> pty module).
> 

Thanks!

> +++ b/Doc/Zsh/mod_clone.yo
> @@ -39,11 +39,30 @@ enditemize()
>  
>  This does not apply when cloning to an em(unused) vc.
>  
> +It is possible however to clone zsh onto a xterm and that zsh process
> +to lead the session attached to that terminal by using tt(xterm)'s slave
> +mode in conjunction with an utility like tt(socat) that can create a
> +pseudo-terminal pair:
>  
> +example(socat pty,link=pty,wait-slave,echo=0 'exec:xterm -Spty/3,nofork,fdout=3,fdin=3' &
> +        clone pty; (($!)) || { IFS= read -r WINDOWID && ((WINDOWID = 0x$WINDOWID));})

There's a race condition here («clone» might run before «./pty» is
created).  Is it worthwhile to point it out in the text, or add
a «sleep» in the example?

By the way, WDYT of adding a concept index entry (e.g., «cindex(tty,
cloning the shell onto an unused)») at the top of the file?  I think the
existing cindex entries won't help someone who doesn't know what the
module is called to discover it.

More later…

Cheers,

Daniel

Re: [PATCH] [doc] clone module using xterm's slave mode

[Stephane Chazelas]

2020-05-19 01:01:40 +0000, Daniel Shahaf:
[...]
> There's a race condition here («clone» might run before «./pty» is
> created).  Is it worthwhile to point it out in the text, or add
> a «sleep» in the example?
[...]

You're right, maybe a better approach would be to supply a
contrib function for that which could be extended to other
terminal emulators like:

clone_on_new_terminal() {
  local terminal_cmd setup
  case $1 in
    (*xterm*)
      terminal_cmd="$1 -Sunused/3"
      setup='IFS= read -r WINDOWID'
      ;;
    (*rxvt*)
      terminal_cmd="$1 -pty-fd 3"
      setup=
      ;;
    (*)
      printf >&2 '"%s" terminal not supported\n' "$1"
      return 1
      ;;
  esac
      
  socat -d -d PTY,wait-slave,echo=0 "exec:$terminal_cmd,nofork,fdout=3,fdin=3" 2>&1 | {
    local -a fields
    IFS=' ' read -rA fields
    clone $fields[-1]
    if (($!)); then
      cat >&2
    else
      eval "$setup"
    fi
  }
}

Still a bit brittle as it relies on a specific output format of
socat's debug output. 

> By the way, WDYT of adding a concept index entry (e.g., «cindex(tty,
> cloning the shell onto an unused)») at the top of the file?  I think the
> existing cindex entries won't help someone who doesn't know what the
> module is called to discover it.
[...]

To be honest, I'm not sure I understand what that module is for.

What would be a typical use case?

-- 
Stephane

Re: [PATCH] [doc] clone module using xterm's slave mode

[Daniel Shahaf]

Stephane Chazelas wrote on Tue, 19 May 2020 19:54 +0100:
> 2020-05-19 01:01:40 +0000, Daniel Shahaf:
> [...]
> > There's a race condition here («clone» might run before «./pty» is
> > created).  Is it worthwhile to point it out in the text, or add
> > a «sleep» in the example?  
> [...]
> 
> You're right, maybe a better approach would be to supply a
> contrib function for that which could be extended to other
> terminal emulators like:
> 

I'm fairly certain that that's nothing at all like what I said :)

Anyway, to answer your question, I'd say that's up to you.  The docs
patch is perfectly good and useful as it stands.  A function would be
even better, but if that's not possible for some reason (e.g., because
of the mentioned dependency on «socat»'s debug output format), then I'd
vote for going with the docs patch.

> > By the way, WDYT of adding a concept index entry (e.g., «cindex(tty,
> > cloning the shell onto an unused)») at the top of the file?  I think the
> > existing cindex entries won't help someone who doesn't know what the
> > module is called to discover it.  
> [...]
> 
> To be honest, I'm not sure I understand what that module is for.
> 
> What would be a typical use case?

Not sure.

Cheers,

Daniel