m4: Syscmd

1 
1 13.2 Executing simple commands
1 ==============================
1 
1 Any shell command can be executed, using 'syscmd':
1 
1  -- Builtin: syscmd (SHELL-COMMAND)
1      Executes SHELL-COMMAND as a shell command.
1 
1      The expansion of 'syscmd' is void, _not_ the output from
1      SHELL-COMMAND!  Output or error messages from SHELL-COMMAND are not
1      read by 'm4'.  ⇒Esyscmd, if you need to process the command
1      output.
1 
1      Prior to executing the command, 'm4' flushes its buffers.  The
1      default standard input, output and error of SHELL-COMMAND are the
1      same as those of 'm4'.
1 
1      By default, the SHELL-COMMAND will be used as the argument to the
1      '-c' option of the '/bin/sh' shell (or the version of 'sh'
1      specified by 'command -p getconf PATH', if your system supports
1      that).  If you prefer a different shell, the 'configure' script can
1      be given the option '--with-syscmd-shell=LOCATION' to set the
1      location of an alternative shell at GNU 'm4' installation; the
1      alternative shell must still support '-c'.
1 
1      The macro 'syscmd' is recognized only with parameters.
1 
1      define(`foo', `FOO')
1      =>
1      syscmd(`echo foo')
1      =>foo
1      =>
1 
1    Note how the expansion of 'syscmd' keeps the trailing newline of the
1 command, as well as using the newline that appeared after the macro.
1 
1    The following is an example of SHELL-COMMAND using the same standard
1 input as 'm4':
1 
1      $ echo "m4wrap(\`syscmd(\`cat')')" | m4
1      =>
1 
1    It tells 'm4' to read all of its input before executing the wrapped
1 text, then hand a valid (albeit emptied) pipe as standard input for the
1 'cat' subcommand.  Therefore, you should be careful when using standard
1 input (either by specifying no files, or by passing '-' as a file name
1 on the command line, ⇒Invoking m4 Command line files.), and also
1 invoking subcommands via 'syscmd' or 'esyscmd' that consume data from
1 standard input.  When standard input is a seekable file, the subprocess
1 will pick up with the next character not yet processed by 'm4'; when it
1 is a pipe or other non-seekable file, there is no guarantee how much
1 data will already be buffered by 'm4' and thus unavailable to the child.
1