4.3BSD - /usr/man/cat1/m4.0

M4(1)                                                                    M4(1)


NAME
       m4 - macro processor

SYNOPSIS
       m4 [ files ]

DESCRIPTION
       M4  is  a  macro  processor  intended as a front end for Ratfor, C, and
       other languages.  Each of the argument files is processed in order;  if
       there are no arguments, or if an argument is ‘-’, the standard input is
       read.  The processed text is written on the standard output.

       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 newlines are ignored while  collect‐
       ing  arguments.   Potential  macro names consist of alphabetic letters,
       digits, and underscore ‘_’, where the first character is not a digit.

       Left and right single quotes (`�´) are used to quote strings.  The value
       of a quoted string is the string stripped of the quotes.

       When a macro name is recognized, its arguments are collected by search‐
       ing for a matching right parenthesis.  Macro evaluation  proceeds  nor‐
       mally  during  the collection of the arguments, and any commas or right
       parentheses which happen to turn up within the value of a  nested  call
       are  as  effective as those in the original input text.  After argument
       collection, the value of the macro is pushed back onto the input stream
       and rescanned.

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

       define    The  second  argument  is installed 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
                 n-th argument.  Argument 0 is the name of the macro;  missing
                 arguments are replaced by the null string.

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

       ifdef     If  the  first  argument  is defined, the value is the second
                 argument, otherwise the third.  If there is  no  third  argu‐
                 ment, 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
                 (i.e., `�´).

       divert    M4 maintains 10 output streams, numbered 0-9.  The final out‐
                 put  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) argu‐
                 ment.  Output diverted to a stream other than 0 through 9  is
                 discarded.

       undivert  causes  immediate  output  of  text  from diversions named as
                 arguments, or all diversions if no  argument.   Text  may  be
                 undiverted  into another diversion.  Undiverting discards the
                 diverted text.

       divnum    returns the value of the current output stream.

       dnl       reads and discards characters up to and  including  the  next
                 newline.

       ifelse    has  three  or  more arguments.  If the first argument is the
                 same string as the second, then the value is the third  argu‐
                 ment.  If not, and if there are more than four arguments, the
                 process is repeated with arguments 4, 5, 6 and 7.  Otherwise,
                 the  value  is  either  the  fourth  string, or, if it is not
                 present, null.

       incr      returns the value of its  argument  incremented  by  1.   The
                 value  of  the argument is calculated by interpreting an ini‐
                 tial digit-string as a decimal number.

       eval      evaluates its argument as  an  arithmetic  expression,  using
                 32-bit arithmetic.  Operators include +, -, ∗, /, %, ^ (expo‐
                 nentiation); relationals; parentheses.

       len       returns the number of characters in its argument.

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

       substr    returns a substring of its first argument.  The second  argu‐
                 ment  is  a zero origin number selecting the first character;
                 the third argument indicates the length of the substring.   A
                 missing  third argument is taken to be large enough to extend
                 to the end of the first string.

       translit  transliterates the characters in its first argument from  the
                 set  given  by  the  second  argument to the set given by the
                 third.  No abbreviations are permitted.

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

       sinclude  is identical to include, except that it says nothing  if  the
                 file is inaccessible.

       syscmd    executes  the  UNIX  command given in the first argument.  No
                 value is returned.

       maketemp  fills in a string of XXXXX in its argument with  the  current
                 process id.

       errprint  prints its argument on the diagnostic output file.

       dumpdef   prints current names and definitions, for the named items, or
                 for all if no arguments are given.

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


7th Edition                     April 29, 1985                           M4(1)