m4(1) m4(1)
NAME
m4 - macro processor
SYNOPSIS
m4 [option...] [file...]
DESCRIPTION
The m4 command is a macro processor intended as a front end for C,
assembler, and other languages. Each of the argument files is pro-
cessed in order; if there are no files, or if a filename is -, the
standard input is read. The processed text is written on the standard
output.
OPTIONS
-e Operate interactively. Interrupts are ignored and the output is
unbuffered.
-s Enable line sync output for the C preprocessor (#line...)
-B int Change the size of the push-back and argument collection
buffers (default is 4,096).
-H int Change the size of the symbol table hash array (default is
199). The size should be prime.
-S int Change the size of the call stack (default is 100 slots).
Macros take three slots in the call buffer, and non-macro argu-
ments take one.
-T int Change the size of the token buffer (default is 512 bytes).
To be effective, the above flags must appear before any filenames and
before any -D or -U flags. The sequence of the -D and -U options is
important.
-D name[=val]
Defines name to val or to null in val's absence.
-U name
Undefines name.
-- If the first filename begins with a dash (-), the end of the
command-line options must be marked with --.
Page 1 Reliant UNIX 5.44 Printed 11/98
m4(1) m4(1)
Macro calls have the form:
name(arg1,arg2, ..., argn)
There must be no spaces between the parenthesis and the macro name. 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 alphanumeric characters and underscore, and the first character
must not be a digit.
Leading unquoted blanks, tabs, and newlines are ignored while collect-
ing 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 col-
lection 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 argument collection, the
value of the macro is pushed back onto the input stream and rescanned.
m4 makes available the following built-in macros. These macros may be
redefined, but once this is done the original meaning is lost. Their
values are null unless otherwise stated.
changecom
change left and right comment markers from the default # 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 newline. With two arguments, both
markers are affected. Comment markers may be up to five charac-
ters long.
changequote
changes the left and right hand quote symbols (two arguments) The
symbols may be up to five characters long. changequote without
arguments restores the original values (i.e., ' ').
decr returns the value of its argument decremented by 1.
define
expects two arguments, of which the first is the name of the
macro and the second is its value. Each $n in the replacement
text, where n is a digit, is replaced by the nth argument. Miss-
ing 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).
defn returns the quoted definition of its argument. It is useful for
Page 2 Reliant UNIX 5.44 Printed 11/98
m4(1) m4(1)
renaming macros, especially built-ins.
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 (digitstring) 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 including the next new-
line.
dumpdef
prints current names and definitions, for the named items, or
errprint
prints its argument on the error output file.
eval evaluates its argument as an arithmetic expression, using 32-bit
arithmetic. Operators include +, -, *, /, %, ** (exponentiation),
bitwise &, |, ^, and ~, relationals, parentheses. Octal and hex
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.
ifdef
if the first argument is defined and is not equal to 0 (Null),
the value is the second argument, otherwise the third. If there
is no third argument, the value is null.
ifelse
replaces text in the output text, subject to conditions ifelse
expects 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 the remaining arguments Otherwise, the value is
either the fourth string, or, if it is not present, null.
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 digitstring
as a decimal number.
index
returns the position in its first argument where the second argu-
ment begins (zero origin), or -1 if the second argument does not
Page 3 Reliant UNIX 5.44 Printed 11/98
m4(1) m4(1)
occur.
len returns the number of characters in its argument.
undefine
the expected argument is a macro whose definition is to be
deleted.
maketemp
fills in a string of XXXXX in its argument with the current pro-
cess ID.
m4exit m4
causes immediate exit from m4. Argument 1, if given, is the exit
code; the default is 0.
m4wrap
the first argument will be pushed back to the final EOF.
popdef
deletes the current definition of its argument, exposing the pre-
vious one, if any.
pushdef
like define, but saves any previous definition.
shift
returns all but its first argument. The other arguments are
quoted and pushed back with commas in between. The quoting nulli-
fies the effect of the extra scan that will subsequently be per-
formed.
sinclude
is identical to include, except that m4 says nothing if the file
is inaccessible.
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.
syscmd
executes the Reliant UNIX System command given in the first argu-
ment. No value is returned.
sysval
is the return code from the last call to syscmd.
traceon
switches on the trace for the specified macros.
Page 4 Reliant UNIX 5.44 Printed 11/98
m4(1) m4(1)
If no arguments are specified, turns on tracing for all macros,
including built-ins.
traceoff
turns off trace globally and for any macros specified. Macros
specifically traced by traceon can be untraced only by specific
calls to traceoff.
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.
undivert
supplies all the outputs in numerical order. If arguments are
specified, undivert will supply the requested outputs to the
specified output buffers, in the specified order.
LOCALE
The language of the message texts is governed by the environment vari-
able LCALL, LCMESSAGES or LANG.
When the default is set, the system behaves as if it were not interna-
tionalized, i.e. the message texts are in English. You must change one
of these variables in order to change the language of the message
texts.
Detailed information on the dependencies of the environment variables
and on internationalization in general can be found in the manual
"Programmer's Guide: Internationalization - Localization". Refer also
to environ(5) for information on setting the user environment.
SEE ALSO
cc(1).
Chapter on "m4" in the "Guide to Tools for Programming in C".
Page 5 Reliant UNIX 5.44 Printed 11/98