.. zsh-module-meta::
   :name: zsh/clone
   :summary: A builtin that can clone a running shell onto another terminal.

The ``zsh/clone`` module makes available one builtin command:

.. index:: single: clone; Function

.. index:: single: shell, cloning; Command

.. index:: single: cloning the shell; Command

.. index:: single: terminal; Command

``clone`` :var:`tty`
    
    Creates a forked instance of the current shell, attached to the specified
    :var:`tty`.  In the new shell, the ``PID``, ``PPID`` and ``TTY`` special
    parameters are changed appropriately.  ``$!`` is set to zero in the new
    shell, and to the new shell's PID in the original shell.
    
    The return status of the builtin is zero in both shells if successful,
    and non-zero on error.
    
    The target of ``clone`` should be an unused terminal, such as an unused virtual
    console or a virtual terminal created by
    
    
    .. code-block:: zsh
       :class: 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
    line: when doing clone on a pseudo-terminal, some other session
    ("session" meant as a unix session group, or SID) is already owning
    the terminal. Hence the cloned zsh cannot acquire the pseudo-terminal
    as a controlling tty. That means two things:
    
        
        * the job control signals will go to the sh-started-by-xterm process
        group (that's why we disable INT QUIT and TSTP with trap; otherwise
        the while loop could get suspended or killed)
        * the cloned shell will have job control disabled, and the job
        control keys (control-C, control-\ and control-Z) will not work.
    
    
    This does not apply when cloning to an :emphasis:`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.
    
    ``clone`` is mostly useful as a shell built-in replacement for
    openvt.
    

