16.1 Extensions in GNU M4

This version of m4 contains a few facilities that do not exist in System V m4. These extra facilities are all suppressed by using the ‘-G’ command line option (see section Invoking m4), unless overridden by other command line options.

• In the $n notation for macro arguments, n can contain several digits, while the System V m4 only accepts one digit. This allows macros in GNU m4 to take any number of arguments, and not only nine (see section Arguments to macros).

  This means that define(`foo', `$11') is ambiguous between implementations. To portably choose between grabbing the first parameter and appending 1 to the expansion, or grabbing the eleventh parameter, you can do the following:

  define(`a1', `A1') ⇒ dnl First argument, concatenated with 1 define(`_1', `$1')define(`first1', `_1($@)1') ⇒ dnl Eleventh argument, portable define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))') ⇒ dnl Eleventh argument, GNU style define(`Eleventh', `$11') ⇒ first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') ⇒A1 eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') ⇒k Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') ⇒k

  Also see the argn macro (see section Recursion in m4).

• The divert (see section Diverting output) macro can manage more than 9 diversions. GNU m4 treats all positive numbers as valid diversions, rather than discarding diversions greater than 9.
• Files included with include and sinclude are sought in a user specified search path, if they are not found in the working directory. The search path is specified by the ‘-I’ option and the M4PATH environment variable (see section Searching for include files).
• Arguments to undivert can be non-numeric, in which case the named file will be included uninterpreted in the output (see section Undiverting output).
• Formatted output is supported through the format builtin, which is modeled after the C library function printf (see section Formatting strings (printf-like)).
• Searches and text substitution through basic regular expressions are supported by the regexp (see section Searching for regular expressions) and patsubst (see section Substituting text by regular expression) builtins. Some BSD implementations use extended regular expressions instead.
• The output of shell commands can be read into m4 with esyscmd (see section Reading the output of commands).
• There is indirect access to any builtin macro with builtin (see section Indirect call of builtins).
• Macros can be called indirectly through indir (see section Indirect call of macros).
• The name of the program, the current input file, and the current input line number are accessible through the builtins __program__, __file__, and __line__ (see section Printing current location).
• The format of the output from dumpdef and macro tracing can be controlled with debugmode (see section Controlling debugging output).
• The destination of trace and debug output can be controlled with debugfile (see section Saving debugging output).
• The maketemp (see section Making temporary files) macro behaves like mkstemp, creating a new file with a unique name on every invocation, rather than following the insecure behavior of replacing the trailing ‘X’ characters with the m4 process id.
• POSIX only requires support for the command line options ‘-s’, ‘-D’, and ‘-U’, so all other options accepted by GNU M4 are extensions. See section Invoking m4, for a description of these options.

  The debugging and tracing facilities in GNU m4 are much more extensive than in most other versions of m4.