diff options
Diffstat (limited to 'Doc/Zsh/mod_zpty.yo')
| -rw-r--r-- | Doc/Zsh/mod_zpty.yo | 85 |
1 files changed, 58 insertions, 27 deletions
diff --git a/Doc/Zsh/mod_zpty.yo b/Doc/Zsh/mod_zpty.yo index 664e2fabd..e90b36d09 100644 --- a/Doc/Zsh/mod_zpty.yo +++ b/Doc/Zsh/mod_zpty.yo @@ -5,42 +5,73 @@ The tt(zsh/zpty) module offers one builtin: startitem() findex(zpty) -xitem(tt(zpty) [ tt(-e) ] [ tt(-b) ] var(name) var(command) [ var(args ...) ]) -xitem(tt(zpty) tt(-d) [ var(names) ... ]) -xitem(tt(zpty) tt(-w) [ tt(-n) ] var(name) var(strings ...)) -xitem(tt(zpty) tt(-r) var(name) [ var(param) [ var(pattern) ] ]) -xitem(tt(zpty) tt(-t) var(name)) -item(tt(zpty) [ tt(-L) ])( +item(tt(zpty) [ tt(-e) ] [ tt(-b) ] var(name) var(command) [ var(args ...) ])( In the first form, the var(command) is started with the var(args) as arguments. 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) given is used to refer to this -command in later calls to tt(pty). With the tt(-e) option given, the -pseudo-terminal will be set up so that input characters are echoed and -with the tt(-b) option given, input and output from and to the -pseudo-terminal will be blocking. - -The second form with the tt(-d) option is used to delete commands -previously started by supplying a list of their var(name)s. If no +interactive environment. The var(name) is used to refer to this command +in later calls to tt(zpty). + +With the tt(-e) option, the pseudo-terminal is set up so that input +characters are echoed. + +With the tt(-b) option, input to and output from the pseudo-terminal are +made non-blocking. +) +item(tt(zpty) tt(-d) [ var(names) ... ])( +The second form, with the tt(-d) option, is used to delete commands +previously started, by supplying a list of their var(name)s. If no var(names) are given, all commands are deleted. Deleting a command causes the HUP signal to be sent to the corresponding process. - -The tt(-w) option can be used to send the command var(name) the given +) +item(tt(zpty) tt(-w) [ tt(-n) ] var(name) [ var(strings ...) ])( +The tt(-w) option can be used to send the to command var(name) the given var(strings) as input (separated by spaces). If the tt(-n) option is -not given, a newline will be added at the end. +em(not) given, a newline is added at the end. -The tt(-r) option can be used to read the output of the command -var(name). Without a var(param) argument, the string read will be -printed to standard output. With a var(param) argument, the string -read will be put in the parameter named var(param). If the -var(pattern) is also given, output will be read until the whole string -read matches the var(pattern). +If no var(strings) are 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 tt(-t) option can be used to test whether the command var(name) is -still running. It returns a zero value if the command is running and -a non-zero value otherwise. +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. +) +item(tt(zpty) tt(-r) [ tt(-t) ] var(name) [ var(param) [ var(pattern) ] ])( +The tt(-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 value is +zero if any output is copied. -The last form without any arguments is used to list the commands +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 value 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 +value is zero if the string read matches the pattern, or if the command +has exited but at least one character could still be read. 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 value is +non-zero. + +In all cases, the return value is non-zero if nothing could be read, and +is tt(2) if this is because the command has finished. + +If the tt(-r) option is combined with the tt(-t) option, tt(zpty) tests +whether output is available before trying to read. If no output is +available, tt(zpty) immediately returns the value tt(1). +) +item(tt(zpty) tt(-t) var(name))( +The tt(-t) option without the tt(-r) option can be used to test +whether the command var(name) is still running. It returns a zero +value if the command is running and a non-zero value otherwise. +) +item(tt(zpty) [ tt(-L) ])( +The last form, without any arguments, is used to list the commands currently defined. If the tt(-L) option is given, this is done in the form of calls to the tt(zpty) builtin. ) |