.. zsh-module-meta::
   :name: zsh/zpty
   :summary: A builtin for starting a command in a pseudo-terminal.

The ``zsh/zpty`` module offers one builtin:

.. index:: single: zpty; Function

``zpty`` [ ``-e`` ] [ ``-b`` ] :var:`name` [ :var:`arg` ... ]
    
    The arguments following :var:`name` are concatenated with spaces between,
    then executed as a command, as if passed to the ``eval`` builtin.  The
    command runs under a newly assigned pseudo-terminal; this is useful for
    running commands non-interactively which expect an interactive
    environment.  The :var:`name` is not part of the command, but is used to
    refer to this command in later calls to ``zpty``.
    
    With the ``-e`` option, the pseudo-terminal is set up so that input
    characters are echoed.
    
    With the ``-b`` option, input to and output from the pseudo-terminal are
    made non-blocking.
    
    The shell parameter ``REPLY`` is set to the file descriptor assigned to
    the master side of the pseudo-terminal.  This allows the terminal to be
    monitored with ZLE descriptor handlers (see the description of option
    ``-F`` for ``zle`` builtin in :zshsectref:`Zle Builtins <zshzle>`)
    or manipulated with ``sysread`` and ``syswrite`` builtins
    (see :zshsectref:`The zsh/system Module <zshmodules>`).
    :emphasis:`Warning`: Use of ``sysread``
    and ``syswrite`` is :emphasis:`not` recommended; use ``zpty -r`` and ``zpty -w``
    unless you know exactly what you are doing.
    

``zpty`` ``-d`` [ :var:`name` ... ]
    
    The ``-d`` option is used to delete commands previously started, by
    supplying a list of their :var:`name`\s.  If no :var:`name` is given, all
    commands are deleted.  Deleting a command causes the HUP signal to be sent
    to the corresponding process.  It is not a good idea to use this form in a
    subshell, as it will kill the command but leave the parent shell confused
    about the state, and it may try to kill another process that re-used the
    process ID.
    

``zpty`` ``-w`` [ ``-n`` ] :var:`name` [ :var:`string` ... ]
    
    The ``-w`` option can be used to send the to command :var:`name` the given
    :var:`string`\s as input (separated by spaces).  If the ``-n`` option is
    :emphasis:`not` given, a newline is added at the end.
    
    If no :var:`string` is provided, the standard input is copied to the
    pseudo-terminal; this may stop before copying the full input if the
    pseudo-terminal is non-blocking.  The exact input is always copied:
    the ``-n`` option is not applied.
    
    Note that the command under the pseudo-terminal sees this input as if it
    were typed, so beware when sending special tty driver characters such as
    word-erase, line-kill, and end-of-file.
    

``zpty`` ``-r`` [ ``-mt`` ] :var:`name` [ :var:`param` [ :var:`pattern` ] ]
    
    The ``-r`` option can be used to read the output of the command :var:`name`.
    With only a :var:`name` argument, the output read is copied to the standard
    output.  Unless the pseudo-terminal is non-blocking, copying continues
    until the command under the pseudo-terminal exits; when non-blocking, only
    as much output as is immediately available is copied.  The return status is
    zero if any output is copied.
    
    When also given a :var:`param` argument, at most one line is read and stored
    in the parameter named :var:`param`.  Less than a full line may be read if
    the pseudo-terminal is non-blocking.  The return status is zero if at least
    one character is stored in :var:`param`.
    
    If a :var:`pattern` is given as well, output is read until the whole string
    read matches the :var:`pattern`, even in the non-blocking case.  The return
    status is zero if the string read matches the pattern, or if the command
    has exited but at least one character could still be read.  If the option
    ``-m`` is present, the return status is zero only if the pattern matches.
    As of this writing, a maximum of one megabyte of output can be consumed
    this way; if a full megabyte is read without matching the pattern, the
    return status is non-zero.
    
    In all cases, the return status is non-zero if nothing could be read, and
    is ``2`` if this is because the command has finished.
    
    If the ``-r`` option is combined with the ``-t`` option, ``zpty`` tests
    whether output is available before trying to read.  If no output is
    available, ``zpty`` immediately returns the status ``1``.  When used
    with a :var:`pattern`, the behaviour on a failed poll is similar to
    when the command has exited:  the return value is zero if at least
    one character could still be read even if the pattern failed to match.
    

``zpty`` ``-t`` :var:`name`
    
    The ``-t`` option without the ``-r`` option can be used to test whether the
    command :var:`name` is still running.  It returns a zero status if the command
    is running and a non-zero value otherwise.  Note that this does not indicate
    whether or not any output is available to read.
    

``zpty`` [ ``-L`` ]
    
    The last form, without any arguments, is used to list the commands
    currently defined.  If the ``-L`` option is given, this is done in the
    form of calls to the ``zpty`` builtin.
    

