M4(1)                                BSD                                 M4(1)



NAME
     m4 - macro processor

SYNOPSIS
     m4 [ file ... ]

DESCRIPTION
     m4 is a macro processor intended as a front end for Ratfor, C, and other
     languages.  It processes each file in order.  If there are no arguments,
     or if an argument is -, m4 reads the standard input.  It writes the
     processed text on the standard output.

     Macro calls have the form

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

     You must place a left parenthesis immediately after the name of the macro
     if you want to specify arguments.  Leading unquoted blanks, tabs, and
     newlines are ignored while collecting arguments. Potential macro names
     consist of alphabetic letters, digits, and underscore characters, where
     the first character is not a digit.

     Use left and right single quotation marks (`') to quote strings.  The
     value of a quoted string is the string stripped of the quotes.

     When m4 recognizes a macro name, it collects the macro's arguments by
     searching for a matching right parenthesis.  Macro evaluation proceeds
     normally during the collection of the arguments, and any commas or right
     parentheses that appear within the value of a nested call are as
     effective as those in the original input text.  After argument
     collection, m4 pushes the value of the macro back into the input stream
     and scans it again.

BUILT-IN MACROS
     m4 uses the built-in macros described below.  You can redefine them, but
     once you do so, the original meaning is lost.  Their values are null
     unless otherwise stated.

     define    Install the second argument as the value of the macro whose
               name is the first argument.  Each occurrence of $n in the
               replacement text, where n is a digit, is replaced by the nth
               argument.  Argument 0 is the name of the macro; the null string
               replaces missing arguments.

     undefine  Remove the definition of the macro named in its argument.

     ifdef     If the first argument is defined, the value is the second
               argument; otherwise, the value is the third.  If there is no
               third argument, the value is null.  The word UNIX is predefined
               on UNIX versions of m4.

     changequote
               Change quote characters to the first and second arguments.
               changequote without arguments restores the original values
               (that is, `').

     divert    Change the current output stream to its digit-string argument.
               Discard output diverted to a stream other than 0 through 9.  m4
               maintains 10 output streams, numbered 0 through 9.  The final
               output is the concatenation of the streams in numerical order;
               initially, stream 0 is the current stream.

     undivert  Produce immediate output of text from diversions named as
               arguments, or all diversions if no argument is present.  You
               can undivert text into another diversion.  Undiverting discards
               the diverted text.

     divnum    Return the value of the current output stream.

     dnl       Read and discard characters up to and including the next
               newline.

     ifelse    There are three or more arguments. If the first argument is the
               same string as the second, then the value in the third
               argument.  If this is not the case, and there are more than
               four arguments, repeat the process with arguments 4, 5, 6, and
               7.  Otherwise, the value is either the fourth string (if
               present) or null.

     incr      Return the value of its argument incremented by one.  Calculate
               the value of the argument by interpreting an initial digit-
               string as a decimal number.

     eval      Evaluate the argument as an arithmetic expression, using 32-bit
               arithmetic.  Operators include +, -, *, /, %, and ^
               (exponentiation); relationals; and parentheses.

     len       Return the number of characters in the argument.

     index     Return the position in the first argument where the second
               argument begins (zero origin), or -1 if the second argument
               does not occur.

     substr    Return a substring of the first argument.  The second argument
               is a zero origin number selecting the first character.  The
               third argument indicates the length of the substring.  A
               missing third argument is assumed to be large enough to extend
               to the end of the first string.

     translit  Transliterate the characters in the first argument from the set
               given by the second argument to the set given by the third.
               You cannot use abbreviations.

     include   Return the contents of the file named in the argument.

     sinclude  Perform the same function as include, but say nothing if the
               file is inaccessible.

     syscmd    Execute the UNIX command given in the first argument.  Return
               no value.

     maketemp  Fill in a string of XXXXX in its argument with the current
               process ID.

     errprint  Print the argument on the diagnostic output file.

     dumpdef   Print current names and definitions for the named items, or for
               all items, if you do not specify an argument.

SEE ALSO
     ratfor(1);
     B. W. Kernighan and D. M. Ritchie, The M4 Macro Processor.