12. Running shell commands

There are a few builtin macros in m4 that allow you to run shell commands from within m4.

Note that the definition of a valid shell command is system dependent. On UNIX systems, this is the typical /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 /bin/sh, and also demonstrate how to quit early with a known exit value if this is not the case.

12.1 Determining the platform

Sometimes it is desirable for an input file to know which platform m4 is running on. GNU m4 provides several macros that are predefined to expand to the empty string; checking for their existence will confirm platform details.

Optional builtin: __gnu__

Optional builtin: __os2__

Optional builtin: os2

Optional builtin: __unix__

Optional builtin: unix

Optional builtin: __windows__

Optional builtin: windows

Each of these macros is conditionally defined as needed to describe the environment of m4. If defined, each macro expands to the empty string.

When GNU extensions are in effect (that is, when you did not use the `-G' option, see section Invoking m4), GNU m4 will define the macro __gnu__ to expand to the empty string.

__gnu__
⇒
ifdef(`__gnu__', `Extensions are active')
⇒Extensions are active

On UNIX systems, GNU m4 will define __unix__ by default, or unix when the `-G' option is specified.

On native Windows systems, GNU m4 will define __windows__ by default, or windows when the `-G' option is specified.

On OS/2 systems, GNU m4 will define __os2__ by default, or os2 when the `-G' option is specified.

If GNU m4 does not provide a platform macro for your system, please report that as a bug.

define(`provided', `0')
⇒
ifdef(`__unix__', `define(`provided', incr(provided))')
⇒
ifdef(`__windows__', `define(`provided', incr(provided))')
⇒
ifdef(`__os2__', `define(`provided', incr(provided))')
⇒
provided
⇒1

12.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 section Reading the output of commands, if you need to process the command output.

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

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.

12.3 Reading the output of commands

If you want m4 to read the output of a shell command, use esyscmd:

Builtin: esyscmd (shell-command)

Expands to the standard output of the shell command shell-command.

Prior to executing the command, m4 flushes its output buffers. The default standard input and error output of shell-command are the same as those of m4. The error output of shell-command is not a part of the expansion: it will appear along with the error output of m4.

The macro esyscmd is recognized only with parameters.

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

Note how the expansion of esyscmd keeps the trailing newline of the command, as well as using the newline that appeared after the macro.

12.4 Exit status

To see whether a shell command succeeded, use sysval:

Builtin: sysval

Expands to the exit status of the last shell command run with syscmd or esyscmd. Expands to 0 if no command has been run yet.

syscmd(`false')
⇒
ifelse(sysval, `0', `zero', `non-zero')
⇒non-zero
syscmd(`exit 2')
⇒
sysval
⇒2
syscmd(`true')
⇒
sysval
⇒0
esyscmd(`false')
⇒
ifelse(sysval, `0', `zero', `non-zero')
⇒non-zero
esyscmd(`exit 2')
⇒
sysval
⇒2
esyscmd(`true')
⇒
sysval
⇒0

sysval results in 127 if there was a problem executing the command, for example, if the system-imposed argument length is exceeded, or if there were not enough resources to fork. It is not possible to distinguish between failed execution and successful execution that had an exit status of 127.

On UNIX platforms, where it is possible to detect when command execution is terminated by a signal, rather than a normal exit, the result is the signal number shifted left by eight bits.

dnl This test assumes kill is a shell builtin, and that signals are
dnl recognizable.
ifdef(`__unix__', ,
      `errprint(` skipping: syscmd does not have unix semantics
')m4exit(`77')')dnl
syscmd(`kill -13 $$')
⇒
sysval
⇒3328
esyscmd(`kill -9 $$')
⇒
sysval
⇒2304

12.5 Making names for temporary files

Commands specified to syscmd or esyscmd might need a temporary file, for output or for some other purpose. There is a builtin macro, maketemp, for making temporary file names:

Builtin: maketemp (template)

Expands to a name of a new, empty file, made from the string template, which should end with the string `XXXXXX'. The six X characters are then replaced with random data, in order to make the file name unique.

The macro maketemp is recognized only with parameters.

maketemp(`/tmp/fooXXXXXX')
⇒/tmp/fooa07346

This document was generated by System Administrator on September, 23 2007 using texi2html 1.70.