DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(m4.info.gz) Invoking m4

Info Catalog (m4.info.gz) History (m4.info.gz) Preliminaries (m4.info.gz) Bugs
 
 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 ( 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.   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.   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 
      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 (
 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.   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.  
      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.   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.   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' ( 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
 ( 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.
 
Info Catalog (m4.info.gz) History (m4.info.gz) Preliminaries (m4.info.gz) Bugs
automatically generated byinfo2html