M4(1) M4(1)
NAME
m4 - macro processor
SYNOPSIS
m4 [ -pprefix ] [ -t ] [ -pprefix ] [ -t ] [ -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.
Page 1 Plan 9 (printed 12/22/24)
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
Page 2 Plan 9 (printed 12/22/24)
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
Page 3 Plan 9 (printed 12/22/24)
M4(1) M4(1)
argument. Text may be undiverted into another
diversion. Undiverting discards the diverted
text.
The -p option causes m4 to add the given prefix character to
the names of predefined macros; typically the prefix is a
Unicode character, to reduce the chance of a clash with
macro names in the input text. The -t option produces a
trace on standard error.
M4 otherwise 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
Page 4 Plan 9 (printed 12/22/24)