open-process: new ?fdno option for selecting stream fd.

If, for instance ?2 is specified in the mode string argument
of open-process and related functions, this means that the
file descriptor 2 of the process will be used as the data
source (or sink) for the stream that is returned by the
function. With this feature we can easily read the standard
error of a process while leaving its standard output
unredirected.

* stream.c (do_parse_mode): Parse the ? mode option.
(open_subprocess): Check for the presence of the alternative
file descriptor in the stdio_mode structure, and and use it
isntead of STDIN_FILENO or STDOUT_FILENO.

* stream.h (struct stdio_mode): New member, streamfd.
(stdio_mode_init_blank, stdio_mode_init_r,
stdio_mode_init_rpb, stdio_mode_init_blank, stdio_mode_init_r,
stdio_mode_init_rpb): Update initializer macros to cover the
new member, setting it to the default value -1 (not
specified).

* txr.1: Documented.

1 files changed, 37 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index ec0a09b9..f20e0963 100644
--- a/txr.1
+++ b/txr.1
@@ -62988,7 +62988,7 @@ Note that it permits no whitespace characters:
 .mets < mode := { < selector [ + ] | + }
 .mets < selector := { r | w | a | m | T }
 .mets < options := { b | x | l | u | i | n | < digit |
-.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \  <> z[ digit ] | < redirection }
+.mets \ \ \ \ \ \ \ \ \ \ \ \ \ \  <> z[ digit ] | < redirection | >> ? fdno }
 .mets < digit := { 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }
 .onom
 
@@ -63160,6 +63160,17 @@ in mode strings that are passed to the
 function; the syntax performs I/O redirections in the child process
 created by that function, and is described in that function's
 documentation.
+.meIP >> ? fdno
+Like
+.metn redirection ,
+this option refers to syntax which only has an effect in
+mode strings that are passed to the
+.code open-process
+function. The syntax selects an alternative file descriptor
+to connect to the returned stream. This is described in the
+documentation for
+.code open-process
+function.
 .RE
 .IP
 The
@@ -66219,6 +66230,31 @@ to standard output, standard input is connected to the null device,
 and descriptor 27 is redirected to descriptor 31.
 
 The
+.meta mode-string
+argument of
+.code open-process
+also supports a special
+.mono
+.meti >> ? fdno
+.onom
+syntax. This syntax specifies an alternative file descriptor in
+the process to which the returned stream should be connected.
+By default, when the process is opened for writing, its standard
+output descriptpr 1 is used, and when it is opened for reading,
+its standard input descriptor 0 is used. This option overrides the
+choice of descriptor. The
+.meta fdno
+portion of the syntax must be a sequence of decimal digits, immediately
+following the
+.code ?
+character. For example, the mode string
+.str ?2
+specifies that the process is to be open for input, such that
+the input stream captures the standard error output of
+that process. In this situation, the standard output will not be
+captured; it remains unredirected.
+
+The
 .code open-subprocess
 function is a variant of
 .codn open-process .