From c5381b85ed6e5466a5eec780480b429878bdec5d Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Wed, 8 May 2002 13:13:52 +0000 Subject: 17081: New zselect module and documentation. --- Doc/Zsh/mod_zselect.yo | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Doc/Zsh/mod_zselect.yo (limited to 'Doc/Zsh/mod_zselect.yo') diff --git a/Doc/Zsh/mod_zselect.yo b/Doc/Zsh/mod_zselect.yo new file mode 100644 index 000000000..506ef033c --- /dev/null +++ b/Doc/Zsh/mod_zselect.yo @@ -0,0 +1,66 @@ +COMMENT(!MOD!zsh/zselect +Block and return when file descriptors are ready. +!MOD!) +The tt(zsh/zselect) module makes available one builtin command: + +startitem() +findex(zselect) +cindex(select, system call) +cindex(file descriptors, waiting for) +item(tt(zselect) [ tt(-rwe) tt(-t) var(timeout) tt(-a) var(array) ] [ var(fd) ... ])( +The tt(zselect) builtin is a front-end to the `select' system call, which +blocks until a file descriptor is ready for reading or writing, or has an +error condition, with an optional timeout. If this is not available on +your system, the command prints an error message and returns status 2 +(normal errors return status 1). For more information, see your systems +documentation for manref(select)(3). Note there is no connection with the +shell builtin of the same name. + +Arguments and options may be intermingled in any order. Non-option +arguments are file descriptors, which must be decimal integers. By +default, file descriptors are to be tested for reading, i.e. tt(zselect) +will return when data is availble to be read from the file descriptor, or +more precisely, when a read operation from the file descriptor will not +block. After a tt(-r), tt(-w) and tt(-e), the given file descriptors are +to be tested for reading, writing, or error conditions. These options and +an arbitrary list of file descriptors may be given in any order. + +(The presence of an `error condition' is not well defined in the +documentation for many implementations of the select system call. +According to recent versions of the POSIX specification, it is really an +em(exception) condition, of which the only standard example is out-of-band +data received on a socket. So zsh users are unlikely to find the tt(-e) +option useful.) + +The option `tt(-t) var(timeout)' specifies a timeout in hundredths of a +second. This may be zero, in which case the file descriptors will simply +be polled and tt(zselect) will return immediately. It is possible to call +zselect with no file descriptors and a non-zero timeout for use as a +finer-grained replacement for `sleep'; not, however, the return status is +always 1 for a timeout. + +The option `tt(-a) var(array)' indicates that tt(array) should be set to +indicate the file descriptor(s) which are ready. If the option is not +given, the array tt(reply) will be used for this purpose. The array will +contain a string similar to the arguments for tt(zselect). For example, + +example(zselect -t 0 -r 0 -w 1) + +might return immediately with status 0 and tt($reply) containing `tt(-r 0 -w +1)' to show that both file descriptors are ready for the requested +operations. + +The option `tt(-A) var(assoc)' indicates that the associative array +tt(assoc) should be set to indicate the file descriptor(s) which are +ready. This option overrides the option tt(-a), nor will tt(reply) be +modified. The keys of tt(assoc) are the file descriptors, and the +corresponding values are any of the characters `tt(rwe)' to indicate the +condition. + +The command returns 0 if some file descriptors are ready for reading. If +the operation timed out, or a timeout of 0 was given and no file +descriptors were ready, or there was an error, it returns status 1 and +the array will not be set (nor modified in any way). If there was an error +in the select operation the appropriate error message is printed. +) +enditem() -- cgit 1.4.1