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. See 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, see Invoking m4), 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.