[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
m4
The format of the m4
command is:
|
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. POSIX requires m4
to
recognize arguments intermixed with files, even when
POSIXLY_CORRECT
is set in the environment. Most options take
effect at startup regardless of their position, but some are documented
below as taking effect after any files that occurred earlier in the
command line. 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, m4 -QPDfoo -d a -df is equivalent to m4 -Q -P -D foo -d -df -- ./a, although the latter form is considered canonical.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 or performing any other
actions.
--version
Print the version number of the program on standard output, then
immediately exit m4
without reading any input files or
performing any other actions.
-E
--fatal-warnings
Controls the effect of warnings. If unspecified, then execution continues and exit status is unaffected when a warning is printed. If specified exactly once, warnings become fatal; when one is issued, execution continues, but the exit status will be non-zero. If specified multiple times, then execution halts with non-zero status the first time a warning is issued. The introduction of behavior levels is new to M4 1.4.9; for behavior consistent with earlier versions, you should specify ‘-E’ twice.
-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.
--warn-macro-sequence[=regexp]
Issue a warning if the regular expression regexp has a non-empty
match in any macro definition (either by define
or
pushdef
). Empty matches are ignored; therefore, supplying the
empty string as regexp disables any warning. If the optional
regexp is not supplied, then the default regular expression is
‘\$\({[^}]*}\|[0-9][0-9]+\)’ (a literal ‘$’ followed by
multiple digits or by an open brace), since these sequences will
change semantics in the default operation of GNU M4 2.0 (due
to a change in how more than 9 arguments in a macro definition will be
handled, see section Arguments to macros). Providing an alternate regular
expression can provide a useful reverse lookup feature of finding
where a macro is defined to have a given definition.
-W regexp
--word-regexp=regexp
Use regexp as an alternative syntax for macro names. This
experimental option will not be present in all GNU m4
implementations (see section Changing the lexical structure of words).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. 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 with respect to file names 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 section Searching for include files, 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. Order is significant with respect to file names. This
option 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 next newline that does not occur in the middle of a quoted string or comment.
define(`twoline', `1 2') ⇒#line 2 "stdin" ⇒ changecom(`/*', `*/') ⇒ define(`comment', `/*1 2*/') ⇒#line 5 ⇒ dnl no line hello ⇒#line 7 ⇒hello twoline ⇒1 ⇒#line 8 ⇒2 comment ⇒/*1 ⇒2*/ one comment `two three' ⇒#line 10 ⇒one /*1 ⇒2*/ two ⇒three goodbye ⇒#line 12 ⇒goodbye |
-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. Order is significant with respect to file names.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 and operating system constraints) in GNU
m4
.
-g
--gnu
Enable all the extensions in this implementation. In this release of
M4, this option is always on by default; it is currently only useful
when overriding a prior use of ‘--traditional’. However, having
GNU behavior as default makes it impossible to write a
strictly POSIX-compliant client that avoids all incompatible
GNU M4 extensions, since such a client would have to use the
non-POSIX command-line option to force full POSIX
behavior. Thus, a future version of M4 will be changed to implicitly
use the option ‘--traditional’ if the environment variable
POSIXLY_CORRECT
is set. Projects that intentionally use
GNU extensions should consider using ‘--gnu’ to state
their intentions, so that the project will not mysteriously break if the
user upgrades to a newer M4 and has POSIXLY_CORRECT
set in their
environment.
-G
--traditional
Suppress all the extensions made in this implementation, compared to the
System V version. See section Compatibility with other versions of m4
, 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 defaults to unlimited on platforms that can detect stack overflow, and to 1024 levels otherwise. A value of zero means unlimited; but then heavily nested code could potentially cause a stack overflow.
The precise effect of this option is more correctly associated
with textual nesting than dynamic recursion. It has been useful
when some complex m4
input was generated by mechanical means, and
also in diagnosing recursive algorithms that do not scale well.
Most users never need to change this option from its default.
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 section Compatibility with other versions of m4
). 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNU m4
comes with a feature of freezing internal state
(see section Fast loading of frozen state). 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section Controlling debugging output, 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 these options are not used, or
if file is unspecified (only possible for ‘--debugfile’),
debug output goes to standard error; if file is the empty string,
debug output is discarded. See section Saving debugging output, for more details. The
option ‘--debugfile’ may be given more than once, and order is
significant with respect to file names. The spellings ‘-o’ and
‘--error-output’ are misleading and inconsistent with other
GNU tools; for now they are silently accepted as synonyms of
‘--debugfile’ and only recognized once, 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 section Controlling debugging output, 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, and order is significant with respect to file names. See section Tracing macro calls, for more details.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The remaining arguments on the command line are taken to be input file names. If no names are present, standard input is read. A file name of ‘-’ is taken to mean 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.
The options ‘--define’ (‘-D’), ‘--undefine’ (‘-U’), ‘--synclines’ (‘-s’), and ‘--trace’ (‘-t’) only take effect after processing input from any file names that occur earlier on the command line. For example, assume the file ‘foo’ contains:
$ cat foo bar |
The text ‘bar’ can then be redefined over multiple uses of ‘foo’:
$ m4 -Dbar=hello foo -Dbar=world foo ⇒hello ⇒world |
If none of the input files invoked m4exit
(see section Exiting from m4
), 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 section 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.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by root on March 13, 2013 using texi2html 1.82.