summaryrefslogtreecommitdiffstats
path: root/txr.1
diff options
context:
space:
mode:
authorKaz Kylheku <kaz@kylheku.com>2016-05-07 07:15:51 -0700
committerKaz Kylheku <kaz@kylheku.com>2016-05-07 07:15:51 -0700
commitbad7fa72982a65f8e2b57ec0db7c2d2eb80b6737 (patch)
tree5415d9cbb234bd2c3cb0ba93a3a925c6e06f7524 /txr.1
parent038bed1fa17743cbbfe4d219b6798d88254eef2c (diff)
downloadtxr-bad7fa72982a65f8e2b57ec0db7c2d2eb80b6737.tar.gz
txr-bad7fa72982a65f8e2b57ec0db7c2d2eb80b6737.tar.bz2
txr-bad7fa72982a65f8e2b57ec0db7c2d2eb80b6737.zip
New: standard stream redirection for subprocesses.
When subprocesses are created using open-command, open-process, run or sh, any streams not bound by those functions are obtained from *stdin*, *stdout* or *stderr*, as appropriate. Thus manipulating these variables has the effect of redirecting not only local output within the program but over coprocesses as well. * stream.c (struct save_fds): New type. (FDS_IN, FDS_OUT, FDS_ERR): New macros. (fds_init, fds_subst, fds_swizzle, fds_restore): New static functions. (open_command, open_process, run): "Swizzle" and restore the standard file descriptors. * txr.1: Updated documentation of affected function.
Diffstat (limited to 'txr.1')
-rw-r--r--txr.174
1 files changed, 74 insertions, 0 deletions
diff --git a/txr.1 b/txr.1
index 0032d4c9..1007bf6d 100644
--- a/txr.1
+++ b/txr.1
@@ -35214,6 +35214,65 @@ the program's output can be gathered by reading from the returned stream.
When the program finishes output, it will close the stream, which can be
detected as normal end of data.
+The standard input and error file descriptors of an input coprocess
+are obtained from the streams stored in the
+.code *stdin*
+and
+.code *stderr*
+special variables, respectively. Similarly, the standard output and error
+file descriptors of an output coprocess are obtained from the
+.code *stdout*
+and
+.code *stderr*
+special variables. These variables must contain streams on which the
+.code fileno
+function is meaningful, otherwise the operation will fail.
+What this functionality means is that re-binding the special variables
+for standard streams has the effect of redirection. For example,
+the following two expressions achieve the same effect of creating
+a stream which reads the output of the
+.code cat
+program, which reads and produces the contents of the file
+.codn text-file .
+
+.cblk
+ ;; redirect input by rebinding *stdin*
+ (let ((*stdin* (open-file "text-file")))
+ (open-command "cat"))
+
+ ;; redirect input using POSIX shell redirection syntax
+ (open-command "cat < text-file")
+.cble
+
+The following is erroneous:
+
+.cblk
+ ;; (let ((*stdin* (make-string-input-stream "abc")))
+ (open-command "cat"))
+.cble
+
+A string input or output stream doesn't have an operating system file
+descriptor; it cannot be passed to a coprocess.
+
+The streams
+.codn *stdin* ,
+.code *stdout*
+and
+.code *stderr*
+are not synchronized with their underlying file descriptors prior to
+the execution of a coprocess. It is up to the program to ensure that
+previous output to
+.code *stdout*
+or
+.code *stderr*
+is flushed, so that the output of the coprocess isn't re-ordered
+with regard to output produced by the program. Similarly,
+input buffered in
+.code *stdin*
+is not available to the coprocess, even though it has not
+yet been read by the program. The program is responsible for preventing this
+situation also.
+
If a coprocess terminates abnormally or unsuccessfully, an exception is raised.
.SS* Symbols and Packages
@@ -36391,6 +36450,21 @@ value from the failed
.code exec
attempt.
+The standard input, output and error file descriptors of an executed
+command are obtained from the streams stored in the
+.codn *stdin* ,
+.code *stdout*
+and
+.code *stderr*
+special variables, respectively. For a detailed description of the
+behavior and restrictions, see the
+.code open-command
+function, whose description of this mechanism applies to the
+.code run
+and
+.code sh
+function also.
+
Note: as of \*(TX 120, the
.code sh
function is implemented using