m4(1) m4(1)
NAME
m4 - processes macros for C and other languages
SYNOPSIS
m4 [-Bint] [-e] [-Hint] [-s] [-Sint] [-Tint] [-Dname[=val]]
[-Uname] [file]...
ARGUMENTS
-Bint
Changes the size of the push-back and argument
collection buffers from the default of 4096.
-Dname[=val]
Defines name to val or to null in the absense of val.
-e Causes m4 to operate interactively. Interrupts are
ignored and the output is unbuffered.
file Specifies the file to be processed. If this argument
is not specified, or if a dash (-) is used as the
filename, the standard input is read.
-Hint
Changes the size of the symbol table hash array from
the default of 199. The size should be prime.
-s Enables line sync output for the C preprocessor
(#line...).
-Sint
Changes the size of the call stack from the default of
100 slots. Macros take 3 slots, and nonmacro arguments
take 1.
-Tint
Changes the size of the token buffer from the default
of 512 bytes.
-Uname
Undefines name.
DESCRIPTION
m4 is a macro processor intended as a front end for C and
other languages. Each of the argument files is processed in
order. The processed text is written on the standard
output.
To be effective, the options must appear before any
filenames and before any -D or -U options.
Macro calls have the form:
January 1992 1
m4(1) m4(1)
name(arg1,arg2,...,argn)
The right parenthesis, (, must immediately follow the name
of the macro. If the name of a defined macro is not
followed by a (, it is deemed to be a call of that macro
with no arguments. Potential macro names consist of
alphabetic letters, digits, and underscore (_), where the
first character is not a digit.
Leading unquoted blanks, tabs, and newlines are ignored
while 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,
and any commas or right parentheses that happen to turn up
within the value of a nested call are as effective as those
in the original input text. After the argument collection,
the value of the macro is pushed back onto the input stream
and rescanned.
Built-in macros
The m4 program 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.
define
Installs 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; $@ is like $*, but each argument is quoted
(with the current quotes).
undefine
Removes the definition of the macro named in the
argument.
defn Returns the quoted definition of the argument(s). This
macro is useful for renaming macros, especially built-
in macros.
pushdef
Acts similarly to define, but also saves any previous
2 January 1992
m4(1) m4(1)
definition.
popdef
Removes the current definition of the argument(s),
exposing the previous one, if any.
ifdef
Installs the second argument as its value, if the first
argument is defined; otherwise, install the third
argument. If there is no third argument, the value is
null. The word unix is predefined on the UNIX(Reg.)
system versions of m4.
shift
Returns all but the first argument. The other
arguments are quoted and pushed back with commas in
between. The quoting nullifies the effect of the extra
scan that is subsequently performed.
changequote
Changes quote symbols to the first and second
arguments. The symbols may be up to five characters
long. changequote without arguments restores the
original values, that is, ``''.
changecom
Changes left and right comment markers from the default
# and newline. With no arguments, the comment
mechanism is effectively disabled. With one argument,
the left marker becomes the argument and the right
marker becomes newline. With two arguments, both
markers are affected. Comment markers may be up to
five characters long.
divert
Changes the current output stream to its (digit-string)
argument. 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. 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 there is 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
January 1992 3
m4(1) m4(1)
next newline.
ifelse
Provides three or more arguments. 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 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 the argument incremented by 1.
The value of the argument is calculated by interpreting
an initial digit-string as a decimal number.
decr Returns the value of the argument decremented by 1.
eval Evaluates the argument as an arithmetic expression,
using 32-bit arithmetic. Operators include +, -, *, /,
%, ^ (exponentiation), bitwise &, |, ^, and ~ as well
as relationals and parentheses. Octal and hexidecimal
numbers may be specified as 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 Returns the number of characters in the argument.
index
Returns the position in the 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
argument 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 the 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
Acts the same as include, except that nothing is
returned if the file is inaccessible.
4 January 1992
m4(1) m4(1)
syscmd
Executes the system command given in the first
argument. No value is returned.
sysval
Specifies the return code from the last call to syscmd.
maketemp
Fills in a string of XXXXX in the argument with the
current process ID.
m4exit
Causes immediate exit from m4. Argument 1, if given,
is the exit code. The default is 0.
m4wrap
Pushes back argument 1 at final EOF. An example is:
m4wrap(`cleanup()').
errprint
Prints the argument on the diagnostic output file.
dumpdef
Prints current names and definitions for the named
items, or for all items if no arguments are given.
traceon
Turns on tracing for all macros including built-ins,
with no arguments. Otherwise, turns on tracing for
named macros.
traceoff
Turns off tracing globally and for any macros
specified. Macros specifically traced by traceon can
be untraced only by specific calls to traceoff.
EXAMPLES
The command:
m4 file1 file2 > outputfile
runs the m4 macro processor on the files file1 and file2 and
redirects the output into outputfile.
FILES
/usr/bin/m4
Executable file
SEE ALSO
cc(1), cpp(1)
January 1992 5
``m4 Reference,'' in A/UX Programming Languages and Tools,
Volume 2
6 January 1992