The zsh/zpty
module offers one builtin:
zpty
[ -e
] [ -b
] name [ arg ... ]The arguments following 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 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 Zle Builtins) or manipulated with sysread
and
syswrite
(see The zsh/system Module). Warning: Use of sysread
and syswrite
is not recommended; use zpty -r
and zpty -w
unless you know exactly what you are doing.
zpty
-d
[ name ... ]The second form, with the -d
option, is used to delete commands
previously started, by supplying a list of their names. If no
name is given, all commands are deleted. Deleting a command causes
the HUP signal to be sent to the corresponding process.
zpty
-w
[ -n
] name [ string ... ]The -w
option can be used to send the to command name the given
strings as input (separated by spaces). If the -n
option is
not given, a newline is added at the end.
If no 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
] name [ param [ pattern ] ]The -r
option can be used to read the output of the command name.
With only a 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 param argument, at most one line is read and stored in the parameter named 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 param.
If a pattern is given as well, output is read until the whole string
read matches the 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 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
nameThe -t
option without the -r
option can be used to test
whether the command name is still running. It returns a zero
status if the command is running and a non-zero value otherwise.
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.