File: m4.info,  Node: Syscmd,  Next: Esyscmd,  Prev: Platform macros,  Up: Shell commands

13.2 Executing simple commands
==============================

Any shell command can be executed, using ‘syscmd’:

 -- Builtin: syscmd(SHELL-COMMAND)
     Executes SHELL-COMMAND as a shell command.

     The expansion of ‘syscmd’ is void, _not_ the output from
     SHELL-COMMAND!  Output or error messages from SHELL-COMMAND are not
     read by ‘m4’.  *Note Esyscmd::, if you need to process the command
     output.

     Prior to executing the command, ‘m4’ flushes its buffers.  The
     default standard input, output and error of SHELL-COMMAND are the
     same as those of ‘m4’.

     By default, the SHELL-COMMAND will be used as the argument to the
     ‘-c’ option of the ‘/bin/sh’ shell (or the version of ‘sh’
     specified by ‘command -p getconf PATH’, if your system supports
     that).  If you prefer a different shell, the ‘configure’ script can
     be given the option ‘--with-syscmd-shell=LOCATION’ to set the
     location of an alternative shell at GNU ‘m4’ installation; the
     alternative shell must still support ‘-c’.

     The macro ‘syscmd’ is recognized only with parameters.

     define(`foo', `FOO')
     ⇒
     syscmd(`echo foo')
     ⇒foo
     ⇒

   Note how the expansion of ‘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 SHELL-COMMAND using the same standard
input as ‘m4’:

     $ echo "m4wrap(\`syscmd(\`cat')')" | m4
     ⇒

   It tells ‘m4’ to read all of its input before executing the wrapped
text, then hand a valid (albeit emptied) pipe as standard input for the
‘cat’ subcommand.  Therefore, you should be careful when using standard
input (either by specifying no files, or by passing ‘-’ as a file name
on the command line, *note Invoking m4: Command line files.), and also
invoking subcommands via ‘syscmd’ or ‘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 ‘m4’; when it
is a pipe or other non-seekable file, there is no guarantee how much
data will already be buffered by ‘m4’ and thus unavailable to the child.