22.36 The zsh/zpty Module

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 name

The -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.