M4(1) DOMAIN/IX Reference Manual (SYS5) M4(1)
NAME
m4 - macro processor
USAGE
m4 [ options ] [ files ]
DESCRIPTION
M4 is a macro processor intended as a front-end for RATFOR,
C, and other languages. It processes each of the argument
files in order. If there are no files to be processed, or
if a filename is specified as a dash (-), m4 reads the stan-
dard input. It writes the processed text on the standard
output.
Macro calls have the following form:
name(arg1,arg2, ..., argn)
The left parenthesis must immediately follow the name of the
macro. If the name of a defined macro is not followed by a
the left parenthesis, it is interpreted as a call of that
macro with no arguments. Potential macro names consist of
alphabetic letters, digits, and underscores. The first
character is not a digit.
M4 ignores leading unquoted blanks, tabs, and newlines while
it is collecting arguments. 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 searching for a matching right parenthesis. If fewer
arguments are supplied than are in the macro definition, the
trailing arguments are taken to be null. Macro evaluation
proceeds normally during the collection of the arguments.
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, the value of the
macro is pushed back onto the input stream and rescanned.
OPTIONS
-e Operate interactively. Ignore interrupts and pro-
duce unbuffered output.
-s Enable line synchronization output for the C
preprocessor
( #line ...).
-Bint Change the size of the push-back and argument col-
lection buffers from the default of 4096.
-Hint Change the size of the symbol table hash array
Printed 6/10/85 M4-1
M4(1) DOMAIN/IX Reference Manual (SYS5) M4(1)
from the default of 199. The size should be
prime.
-Sint Change the size of the call stack from the default
of 100 slots. Macros take three slots, and non-
macro arguments take one.
-Tint Change the size of the token buffer from the
default of 512 bytes.
To be effective, these flags must appear before any
filenames and before any -D or -U flags:
-Dname[=val]
Define name to val or to null in val's absence.
-Uname Undefine name.
BUILT-IN MACROS
M4 uses the following built-in macros. You may redefine
them, but once this is done 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; missing
arguments are replaced by the null string; $# is
replaced by the number of arguments; $* is
replaced by a list of all the arguments
separated by commas. A $@ is like $* , but each
argument is quoted (with the current quotes).
undefine Remove the definition of the macro named in its
argument.
defn Return the quoted definition of its argument(s).
Useful for renaming macros, especially those
that are built-in.
pushdef Perform an action similar to define, but save
any previous definition.
popdef Remove current definition of its argument(s),
exposing the previous one, if any.
ifdef If the first argument is defined, specify the
value equal to the second argument; otherwise,
make it the third. If there is no third argu-
ment, the value is null. The word unix is
M4-2 Printed 6/10/85
M4(1) DOMAIN/IX Reference Manual (SYS5) M4(1)
predefined on UNIX system versions of m4.
shift Return all but its first argument. Quote the
other arguments and push them back with commas
in between. The quoting nullifies the effect of
the extra scan that will subsequently be per-
formed.
changequote Change quote symbols to the first and second
arguments. The symbols may be up to five char-
acters long. A changequote macro without argu-
ments restores the original values (i.e., `').
changecom Change left and right comment markers from the
default pound sign (#) and new-line. With no
arguments, the comment mechanism is effectively
disabled. With one argument, the left marker
becomes the argument and the right marker
becomes new-line. With two arguments, both
markers are affected. Comment markers may be up
to five characters long.
divert Change the current output stream to its (digit-
string) argument. Discard output diverted to a
stream other than zero through nine. M4 main-
tains 10 output streams, numbered zero through
nine. The final output is the concatenation of
the streams in numerical order; initially stream
0 is the current stream.)
undivert Produce immediate text output from diversions
named as arguments, or all diversions if no
argument exists. Text may be undiverted 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 If the first argument is the same string as the
second, then the value is the third argument.
If not, and if there are more than four argu-
ments, the process is repeated with arguments 4,
5, 6, and 7. Otherwise, the value is the fourth
string, or, if it is not present, the null
string.
incr Return the value of its argument incremented by
one. The value of the argument is calculated by
interpreting an initial digit-string as a
Printed 6/10/85 M4-3
M4(1) DOMAIN/IX Reference Manual (SYS5) M4(1)
decimal number.
decr Return the value of its argument decremented by
one.
eval Evaluate its argument as an arithmetic expres-
sion, using 32-bit arithmetic. Operators
include +, -, *, /, %, ^ (exponentiation), bit-
wise &, |, ^, and ~; relationals; and
parentheses. Octal and hex numbers may be
specified as they are in C. The second argument
specifies the radix for the result; the default
is 10. The third argument may be used to
specify the minimum number of digits in the
result.
len Return the number of characters in its argument.
index Return the position in its first argument where
the second argument begins (zero origin), or -1
if the second argument does not occur.
substr Return 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.
translit Transliterate the characters in its first argu-
ment from the set given by the second argument
to the set given by the third. No abbreviations
are permitted.
include Return the contents of the file named in the
argument.
sinclude Perform a function like include, but do not com-
ment if the file is inaccessible.
syscmd Execute the UNIX system command given in the
first argument. No value is returned.
sysval Represent the return code from the last call to
syscmd.
maketemp Fill in a string of XXXXX in its argument with
the current process ID.
m4exit Immediately exit from m4. Argument 1, if given,
is the exit code; the default is 0.
M4-4 Printed 6/10/85
M4(1) DOMAIN/IX Reference Manual (SYS5) M4(1)
m4wrap Push back argument 1 at final EOF; e.g.,
m4wrap(`cleanup()').
errprint Print its argument on the diagnostic output
file.
dumpdef Print current names and definitions, for the
named items, or for all if no arguments are
given.
traceon With no arguments, turn on tracing for all mac-
ros (including built-ins). Otherwise, turn on
tracing for the named macros.
traceoff Turn off trace globally and for any macros
specified. Macros specifically traced by tra-
ceon can be untraced only by specific calls to
traceoff.
RELATED INFORMATION
cc (1), cpp (1),
Printed 6/10/85 M4-5