Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      07/03/01 14:30:25

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.98
retrieving revision 1.99
diff -u -b -r1.98 -r1.99
--- doc/m4.texinfo      28 Feb 2007 21:31:12 -0000      1.98
+++ doc/m4.texinfo      1 Mar 2007 14:30:25 -0000       1.99
@@ -6351,19 +6351,19 @@
 @node Shell commands
 @chapter Macros for running shell commands
 
address@hidden UNIX commands, running
 @cindex executing shell commands
 @cindex running shell commands
 @cindex shell commands, running
address@hidden UNIX commands, running
 @cindex commands, running shell
 There are a few builtin macros in @code{m4} that allow you to run shell
 commands from within @code{m4}.
 
 Note that the definition of a valid shell command is system dependent.
-On UNIX systems, this is the typical @code{/bin/sh}.  But on other
+On UNIX systems, this is the typical @command{/bin/sh}.  But on other
 systems, such as native Windows, the shell has a different syntax of
 commands that it understands.  Some examples in this chapter assume
address@hidden/bin/sh}, and also demonstrate how to quit early with a known
address@hidden/bin/sh}, and also demonstrate how to quit early with a known
 exit value if this is not the case.
 
 @menu
@@ -6377,6 +6377,8 @@
 
 @node Platform macros
 @section Determining the platform
+
address@hidden platform macros
 Sometimes it is desirable for an input file to know which platform
 @code{m4} is running on.  @acronym{GNU} @code{m4} provides several
 macros that are predefined to expand to the empty string; checking for
@@ -6425,16 +6427,17 @@
 @node Syscmd
 @section Executing simple commands
 
+Any shell command can be executed, using @code{syscmd}:
+
 @deffn {Builtin (m4)} syscmd (@var{shell-command})
-Any shell command can be executed, using @code{syscmd}, which executes
address@hidden as a shell command.
+Executes @var{shell-command} as a shell command.
 
 The expansion of @code{syscmd} is void, @emph{not} the output from
 @var{shell-command}!  Output or error messages from @var{shell-command}
 are not read by @code{m4}.  @xref{Esyscmd}, if you need to process the
 command output.
 
-Prior to executing the command, @code{m4} flushes its output buffers.
+Prior to executing the command, @code{m4} flushes its buffers.
 The default standard input, output and error of @var{shell-command} are
 the same as those of @code{m4}.
 
@@ -6442,7 +6445,7 @@
 m4}) is in effect, @code{syscmd} results in an error, since otherwise an
 input file could execute arbitrary code.
 
-The builtin macro @code{syscmd} is recognized only when given arguments.
+The macro @code{syscmd} is recognized only with parameters.
 @end deffn
 
 @example
@@ -6456,6 +6459,33 @@
 Note how the expansion of @code{syscmd} keeps the trailing newline of
 the command, as well as using the newline that appeared after the macro.
 
+The following is an example of @var{shell-command} using the same
+standard input as @code{m4}:
+
address@hidden The testsuite does not know how to parse pipes from the
address@hidden texinfo.  Fortunately, there are other tests in the testsuite
address@hidden that test this same feature.
address@hidden ignore
address@hidden
+$ @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4}
address@hidden
address@hidden example
+
+It tells @code{m4} to read all of its input before executing the wrapped
+text, then hands a valid (albeit emptied) pipe as standard input for the
address@hidden subcommand.  Therefore, you should be careful when using
+standard input (either by specifying no files, or by passing @samp{-} as
+a file name on the command line, @pxref{Command line files, , Invoking
+m4}), and also invoking subcommands via @code{syscmd} or @code{esyscmd}
+that consume data from standard input.  When standard input is a
+seekable file, the subprocess will pick up with the next character not
+yet processed by @code{m4}; when it is a pipe or other non-seekable
+file, there is no guarantee how much data will already be buffered by
address@hidden and thus unavailable to the child.
+
+Following is an example of how potentially unsafe actions can be
+suppressed.
+
 @comment options: --safer
 @comment status: 1
 @example
@@ -6469,17 +6499,26 @@
 @section Reading the output of commands
 
 @cindex @acronym{GNU} extensions
address@hidden {Builtin (gnu)} esyscmd (@var{shell-command})
 If you want @code{m4} to read the output of a shell command, use
address@hidden, which expands to the standard output of the shell
-command @var{shell-command}.
address@hidden:
 
-Prior to executing the command, @code{m4} flushes its output buffers.
address@hidden {Builtin (gnu)} esyscmd (@var{shell-command})
+Expands to the standard output of the shell command
address@hidden
+
+Prior to executing the command, @code{m4} flushes its buffers.
 The default standard input and standard error of @var{shell-command} are
 the same as those of @code{m4}.  The error output of @var{shell-command}
 is not a part of the expansion: it will appear along with the error
 output of @code{m4}.
 
+When the @option{--safer} option (@pxref{Operation modes, , Invoking
+m4}) is in effect, @code{esyscmd} results in an error, since otherwise
+an input file could execute arbitrary code.
+
+The macro @code{esyscmd} is recognized only with parameters.
address@hidden deffn
+
 @example
 define(`foo', `FOO')
 @result{}
@@ -6491,13 +6530,9 @@
 Note how the expansion of @code{esyscmd} keeps the trailing newline of
 the command, as well as using the newline that appeared after the macro.
 
-When the @option{--safer} option (@pxref{Operation modes, , Invoking
-m4}) is in effect, @code{esyscmd} results in an error, since otherwise
-an input file could execute arbitrary code.
-
-The builtin macro @code{esyscmd} is recognized only when given
-arguments.
address@hidden deffn
+Just as with @code{syscmd}, care must be exercised when sharing standard
+input between @code{m4} and the child process of @code{esyscmd}.
+Likewise, potentially unsafe actions can be suppressed.
 
 @comment options: --safer
 @comment status: 1