M4(1)                                                       M4(1)

     NAME
          m4 - macro processor

     SYNOPSIS
          m4 [ -Dname=value ] [ -Qname=value ] [ -Uname ] [ file ...
          ]

     DESCRIPTION
          M4 is a general-purpose macro processor.  It copies text
          from each of the input files in order (or standard input by
          default), and writes the processed text to the standard out-
          put.

          Macro calls have the form

               name(arg1, arg2, ..., argn)

          The `(' must immediately follow the name of the macro.  If a
          defined macro name is not followed by a `(', it is deemed to
          have no arguments.  Leading unquoted blanks, tabs, and new-
          lines are ignored while collecting arguments.  A comma
          within a nested parenthesis is part of an argument value,
          not an argument separator.  Potential macro names consist of
          alphabetic letters, Unicode characters, digits, and under-
          score `_', where the first character is not a digit.

          Comments begin with the # character and extend to the end of
          that line; the characters in a comment are copied to the
          current output stream unchanged.  The comment start and end
          sequences may be changed using the changecom call described
          below.

          The left and right single quotes (ie, grave and acute
          accents `' ) are used to quote strings.  Because the left
          and right quotes are distinct, quoted strings may nest.  The
          value of a quoted string is the string stripped of the out-
          ermost quotes.  The left and right quote characters may be
          changed using the changequote call described below.

          When m4 recognises a macro name, followed by a `(', it col-
          lects arguments up to a matching right parenthesis.  Macro
          evaluation proceeds normally during this collection, and the
          text produced by those macro calls is interpreted exactly as
          if it had been in the original input stream (in place of the
          corresponding macro call).  Thus, any commas or right paren-
          theses within the value of a nested call are as effective as
          those in the original input text.  (Remember however that
          commas within nested parentheses are not argument separa-
          tors.)  After argument collection, the value of the macro is
          pushed back onto the input stream and rescanned.

     M4(1)                                                       M4(1)

          M4 makes available the following built-in macros.  They may
          be redefined, but once this is done the original meaning is
          lost.  Their values are null unless otherwise stated.

          changecom    Change the starting and ending delimiters for
                       subsequent comments to the first and second
                       arguments.  If the second argument is missing
                       or an empty string, comments will be ended by
                       newline.  If there are no arguments, there are
                       no comments.
          changequote  Change quote characters to the first and second
                       arguments.  Changequote without arguments
                       restores the original values of `'.
          copydef      The second argument is installed with the value
                       of the macro named by the first argument, which
                       may be a built-in macro.  Typically both argu-
                       ments are quoted to prevent too early expan-
                       sion.  A macro can be renamed using copydef
                       followed by undefine.
          define       The second argument is installed as the value
                       of the macro named by the first argument.  When
                       the macro is later called (expanded), each
                       occurrence in the replacement text of $n, where
                       n is a digit, is replaced by the n-th argument
                       of that macro call.  Argument 0 is the name of
                       the macro; missing arguments are replaced by
                       the null string.  If the macro value is the
                       same as its name, or the value is $0, the
                       result is the macro name.  To prevent expansion
                       of a name when redefining a macro, quote the
                       first argument.
          divert       M4 maintains 10 output streams, numbered 0-9.
                       The final output is the concatenation of the
                       streams in numerical order; initially stream 0
                       is the current stream.  The divert macro
                       changes the current output stream to its
                       (digit-string) argument.  Output diverted to a
                       stream other than 0 through 9 is discarded.
          divnum       Returns the value of the current output stream.
          dnl          Reads and discards characters up to and includ-
                       ing the next newline.
          dumpdef      Prints current names and definitions, for the
                       named items, or for all if no arguments are
                       given.
          errprint     Prints its argument on the diagnostic output
                       file.
          eval         Evaluates its argument as an arithmetic expres-
                       sion, using 32-bit arithmetic, and returns the
                       result as a signed decimal integer.  The only
                       literals are decimal integers.  Operators are
                       those of Limbo: the binary operators ||, &&, |,
                       ^, &, == !=, < > >= <=, << >> (arithmetic

     M4(1)                                                       M4(1)

                       shifts), + -, * / %, ** (power); the unary
                       operators +, -, ~, !; and parenthesis.  Opera-
                       tor precedence is the same as in Limbo.  Right
                       shifts are signed.
          ifdef        If the first argument is defined, the value is
                       the second argument, otherwise the third.  If
                       there is no third argument, the value is null.
                       The word inferno is predefined with `inferno'
                       as its replacement text.
          ifelse       Has three or more arguments.  If the first
                       argument is the same string as the second, then
                       the value is the third argument.  If not, the
                       process is repeated with arguments 4, 5, 6 and
                       so on, in groups of three.  If no match is
                       found, the result is the remaining argument
                       (not part of a group of three), or null if none
                       is present.
          include      Returns the contents of the file named in the
                       argument.
          incr         Returns the value of its argument incremented
                       by 1.  The value of the argument is calculated
                       by interpreting an initial digit-string as a
                       decimal number.
          index        Returns the position in its first argument
                       where the second argument begins (zero origin),
                       or -1 if the second argument does not occur.
          len          Returns the number of characters in its argu-
                       ment.
          maketemp     Returns its first argument after replacing any
                       trailing XXXs by the current host name, process
                       ID, and a unique letter.  Normally used to cre-
                       ate unique temporary file names.
          sinclude     The same as include, except that it says noth-
                       ing if the file is inaccessible.
          substr       Returns a substring of its first argument.  The
                       second argument is a zero origin number select-
                       ing the first character; the third argument
                       indicates the length of the substring.  A miss-
                       ing third argument is taken to be large enough
                       to extend to the end of the first string.
          syscmd       Runs the first argument as an sh(1) command.
                       No value is returned.  Note that the output of
                       a command can be redirected to a temporary file
                       named by maketemp, included, and then removed.
          translit     Transliterates the characters in its first
                       argument from the set given by the second argu-
                       ment to the set given by the third.  No abbre-
                       viations are permitted.
          undefine     Removes the definition of the macro named in
                       its argument.
          undivert     Causes immediate output of text from diversions
                       named as arguments, or all diversions if no

     M4(1)                                                       M4(1)

                       argument.  Text may be undiverted into another
                       diversion.  Undiverting discards the diverted
                       text.

          M4 interprets its command line options after installing the
          predefined macro set.  The -D option defines name as a macro
          with the given value; -Q defines name as a macro with the
          given value that is regarded as always quoted (ie, is never
          rescanned).  Neither -D nor -Q may change a predefined
          macro.  The -U option undefines the given macro name, which
          may be one of the predefined macros.

          M4 in Inferno is more closely related to the original m4 in
          Seventh Edition UNIX than its more elaborate relatives in
          System V and POSIX.

     SEE ALSO
          B. W. Kernighan and D. M. Ritchie, The M4 Macro Processor