1.3 Invoking m4

The format of the m4 command is:

     m4 [option...] [file...]

All options begin with `-', or if long option names are used, with `--'. A long option name need not be written completely, any unambiguous prefix is sufficient. Unless POSIXLY_CORRECT is set in the environment, options may be intermixed with files. The argument -- is a marker to denote the end of options.

With short options, options that do not take arguments may be combined into a single command line argument with subsequent options, options with mandatory arguments may be provided either as a single command line argument or as two arguments, and options with optional arguments must be provided as a single argument. In other words, without POSIXLY_CORRECT, m4 -QPDfoo -d a -d+f is equivalent to m4 -Q -P -D foo -d -d+f -- a, although the latter form is considered canonical. (With POSIXLY_CORRECT, it is equivalent to m4 -Q -P -D foo -d -- a ./-d+f).

With long options, options with mandatory arguments may be provided with an equal sign (`=') in a single argument, or as two arguments, and options with optional arguments must be provided as a single argument. In other words, m4 --def foo --debug a is equivalent to m4 --define=foo --debug= -- a, although the latter form is considered canonical (not to mention more robust, in case a future version of m4 introduces an option named --default).

m4 understands the following options, grouped by functionality. Several options control the overall operation of m4:

--help

Print a help summary on standard output, then immediately exit m4 without reading any input files.

--version

Print the version number of the program on standard output, then immediately exit m4 without reading any input files.

-E

--fatal-warnings

Stop execution and exit m4 once the first warning has been issued, considering all of them to be fatal.

-i

--interactive

-e

Makes this invocation of m4 interactive. This means that all output will be unbuffered, and interrupts will be ignored. The spelling -e exists for compatibility with other m4 implementations, and issues a warning because it may be withdrawn in a future version of GNU M4.

-P

--prefix-builtins

Internally modify all builtin macro names so they all start with the prefix `m4_'. For example, using this option, one should write `m4_define' instead of `define', and `m4___file__' instead of `__file__'. This option has no effect if -R is also specified.

-Q

--quiet

--silent

Suppress warnings, such as missing or superfluous arguments in macro calls, or treating the empty string as zero.

-W REGEXP

--word-regexp=REGEXP

Use REGEXP as an alternative syntax for macro names. This experimental option will not be present on all GNU m4 implementations (see Changeword).

Several options allow m4 to behave more like a preprocessor. Macro definitions and deletions can be made on the command line, the search path can be altered, and the output file can track where the input came from. These features occur with the following options:

-D NAME[=VALUE]

--define=NAME[=VALUE]

This enters NAME into the symbol table, before any input files are read. If `=VALUE' is missing, the value is taken to be the empty string. The VALUE can be any string, and the macro can be defined to take arguments, just as if it was defined from within the input. This option may be given more than once; order is significant, and redefining the same NAME loses the previous value.

-I DIRECTORY

--include=DIRECTORY

Make m4 search DIRECTORY for included files that are not found in the current working directory. See Search Path, for more details. This option may be given more than once.

-s

--synclines

Generate synchronization lines, for use by the C preprocessor or other similar tools. This is useful, for example, when m4 is used as a front end to a compiler. Source file name and line number information is conveyed by directives of the form `#line linenum "file"', which are inserted as needed into the middle of the output. Such directives mean that the following line originated or was expanded from the contents of input file file at line linenum. The `"file"' part is often omitted when the file name did not change from the previous directive.

Synchronization directives are always given on complete lines by themselves. When a synchronization discrepancy occurs in the middle of an output line, the associated synchronization directive is delayed until the beginning of the next generated line.

-U NAME

--undefine=NAME

This deletes any predefined meaning NAME might have. Obviously, only predefined macros can be deleted in this way. This option may be given more than once; undefining a NAME that does not have a definition is silently ignored.

There are some limits within m4 that can be tuned. For compatibility, m4 also accepts some options that control limits in other implementations, but which are automatically unbounded (limited only by your hardware constraints) in GNU m4.

-G

--traditional

Suppress all the extensions made in this implementation, compared to the System V version. See Compatibility, for a list of these.

-H NUM

--hashsize=NUM

Make the internal hash table for symbol lookup be NUM entries big. For better performance, the number should be prime, but this is not checked. The default is 509 entries. It should not be necessary to increase this value, unless you define an excessive number of macros.

-L NUM

--nesting-limit=NUM

Artificially limit the nesting of macro calls to NUM levels, stopping program execution if this limit is ever exceeded. When not specified, nesting is limited to 1024 levels.

The precise effect of this option might be more correctly associated with textual nesting than dynamic recursion. It has been useful when some complex m4 input was generated by mechanical means. Most users would never need this option. If shown to be obtrusive, this option (which is still experimental) might well disappear.

This option does not have the ability to break endless rescanning loops, since these do not necessarily consume much memory or stack space. Through clever usage of rescanning loops, one can request complex, time-consuming computations from m4 with useful results. Putting limitations in this area would break m4 power. There are many pathological cases: `define(`a', `a')a' is only the simplest example (but see Compatibility). Expecting GNU m4 to detect these would be a little like expecting a compiler system to detect and diagnose endless loops: it is a quite hard problem in general, if not undecidable!

-B NUM

-S NUM

-T NUM

These options are present for compatibility with System V m4, but do nothing in this implementation. They may disappear in future releases, and issue a warning to that effect.

-N NUM

--diversions=NUM

These options are present only for compatibility with previous versions of GNU m4, and were controlling the number of possible diversions which could be used at the same time. They do nothing, because there is no fixed limit anymore. They may disappear in future releases, and issue a warning to that effect.

GNU m4 comes with a feature of freezing internal state (see Frozen files). This can be used to speed up m4 execution when reusing a common initialization script.

-F FILE

--freeze-state=FILE

Once execution is finished, write out the frozen state on the specified FILE. It is conventional, but not required, for FILE to end in `.m4f'.

-R FILE

--reload-state=FILE

Before execution starts, recover the internal state from the specified frozen FILE. The options -D, -U, and -t take effect after state is reloaded, but before the input files are read.

Finally, there are several options for aiding in debugging m4 scripts.

-d[FLAGS]

--debug[=FLAGS]

Set the debug-level according to the flags FLAGS. The debug-level controls the format and amount of information presented by the debugging functions. See Debug Levels, for more details on the format and meaning of FLAGS. If omitted, FLAGS defaults to `aeq'.

--debugfile=FILE

-o FILE

--error-output=FILE

Redirect dumpdef output, debug messages, and trace output to the named FILE. Warnings, error messages, and errprint output are still printed to standard error. If unspecified, debug output goes to standard error; if empty, debug output is discarded. See Debug Output, for more details. The spellings -o and --error-output are misleading and inconsistent with other GNU tools; for now they are silently accepted as synonyms of --debugfile, but in a future version of M4, using them will cause a warning to be issued.

-l NUM

--arglength=NUM

Restrict the size of the output generated by macro tracing to NUM characters per trace line. If unspecified or zero, output is unlimited. See Debug Levels, for more details.

-t NAME

--trace=NAME

This enables tracing for the macro NAME, at any point where it is defined. NAME need not be defined when this option is given. This option may be given more than once. See Trace, for more details.

The remaining arguments on the command line are taken to be input file names. If no names are present, the standard input is read. A file name of - is taken to mean the standard input. It is conventional, but not required, for input files to end in `.m4'.

The input files are read in the sequence given. Standard input can be read more than once, so the file name - may appear multiple times on the command line; this makes a difference when input is from a terminal or other special file type. It is an error if an input file ends in the middle of argument collection, a comment, or a quoted string.

If none of the input files invoked m4exit (see M4exit), the exit status of m4 will be 0 for success, 1 for general failure (such as problems with reading an input file), and 63 for version mismatch (see Using frozen files).

If you need to read a file whose name starts with a -, you can specify it as `./-file', or use -- to mark the end of options.