m4
PURPOSE
Preprocesses files, expanding macro definitions.
SYNOPSIS
m4 [ options ] [ files ]
DESCRIPTION
The m4 command is a macro processor used as a pre-
processor for C and other languages. You can use it to
process built-in macros or user-defined macros. Each
file is processed in order. If you do not specify a file
or if you give a minus (-) as a file name, m4 reads
standard input. It writes the processed macros to
standard output. Macro calls follow the form:
macroname(argument . . . )
The left parenthesis must immediately follow macroname.
If the left parenthesis does not follow the name of a
defined macro, m4 reads it as a macro call with no argu-
ments. Macro names consist of ASCII alphabetic letters,
digits, and the underscore character (_). Extended char-
acters are not allowed in macro names. The first char-
acter cannot be a digit.
While collecting arguments, m4 ignores unquoted leading
blanks, tabs, and new-line characters. Use single quota-
tion marks to quote strings. The value of a quoted
string is the string with the quotation marks stripped
off.
When m4 recognizes a macro, it collects arguments by
searching for a matching right parenthesis. If you
supply fewer arguments than appear in the macro defi-
nition, m4 considers the trailing arguments in the defi-
nition to be null. Macro evaluation proceeds normally
during the collection of the arguments. All commas or
right parentheses within the value of a nested call are
translated literally; they do not need an escape char-
acter or quotation marks. After collecting arguments, m4
pushes the value of the macro back onto the input stream
and scans again.
BUILT-IN MACROS
The m4 command makes available the following built-in
macros. You may redefine them, but you will lose the
original meaning. The values of these macros are null
unless otherwise stated:
define(name,new_name) Replaces the macro name with the
value of new_name. The new_name
string can take the form "$"n . . .
(where n is a digit). In this
case, each occurrence of n in the
replacement text is replaced by the
n-th argument of name. "$0" is the
name of the macro. The null string
replaced missing arguments. The
number of arguments replaces "$#".
A comma-separated list of all argu-
ments replaces "$*". "$@" acts
like "$*", but each argument is
quoted with the current quotation
character (see changequote).
undefine(name) Removes the definition of name.
defn(name . . . ) Returns the quoted definition of
name.
pushdef(name,new_name)
Redefines name with new_name as in
define, but save any previous defi-
nition.
popdef(name . . . ) Removes the current definition of
name and returns to the previous
definition, if one existed.
ifdef(name,true,[false])
Returns the value of true only if
name is defined, otherwise return
false. If you do not supply false,
its value is null.
Note: The word unix is predefined.
shift(argument . . . )
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 will subse-
quently be performed.
changequote(L,R) Changes quote symbols to L and R.
The symbols can be up to five bytes
long. changequote without argu-
ments restores the original values
(` ').
changecom(Lcom,Rcom) Changes left and right comment
markers from the default "#" and
new-line character to Lcom and
Rcom. With no arguments, the
comment mechanism is disabled.
With one argument, the left marker
becomes the parameter and the right
marker becomes a new-line char-
acter. With two arguments, both
markers are affected. Comment
markers can be up to five bytes
long.
divert(num) Changes the current output stream
to stream num. There are 10 output
streams, numbered 0-9. The final
output is the concatenation of the
streams in numerical order. Ini-
tially, stream 0 is the current
stream. m4 discards output
diverted to a stream other than
0-9.
undivert(num . . . ) Causes immediate output of text
from the specified diversions (or
all diversions if there is no argu-
ment). 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 new-line
character.
ifelse([string1,string2,true,[false]] . . . )
If string1 and string2 are the
same, then the value is true. If
they are not and if there are more
than four arguments, m4 repeats the
process with the additional argu-
ments (4, 5, 6, and 7). Otherwise,
the value is either false or null
if you provide no value for false.
incr(num) Returns the value of its argument
incremented by 1.
decr(num) Returns the value of its argument
decreased by 1.
eval(expr[,num1[,num2]])
Evaluates its first argument as an
arithmetic expression, using 32-bit
arithmetic. The operators you can
use include +, -, "*", /,"%", ^
(exponentiation), bitwise "&", |,
~, and ^ relationals, and paren-
theses. Octal and hex numbers can
be specified as in C. num1 speci-
fies the radix for the result of
the expression. The default radix
is 10. The optional num2 specifies
the minimum number of digits in the
result.
len(string) Returns the number of bytes in
string.
dlen(string) Returns the number of displayable
characters in string; that is, two-
byte extended characters are
counted as one displayable char-
acter.
index(s1,s2) Returns the position in the string
s1 where the string s2 begins (zero
origin), or -1 if the second param-
eter does not occur.
substr(string,position,num)
Returns a substring of string. The
beginning of the substring is
selected with position, and num
indicates the length of the sub-
string. Without num, the substring
includes everything to the end of
the first string.
translit(string,from,to)
Transliterates the characters in
string from the set given by from
to the set given by to. No abbre-
viations are permitted. Two-byte
extended characters are correctly
mapped into the corresponding
replacement characters.
include(file) Returns the contents of file or
displays an error message if it
cannot access the file.
sinclude(file) Returns the contents of file, but
it gives no error message if file
is inaccessible.
syscmd(command) Runs the AIX command. No value is
returned.
sysval Returns the return code from the
last call to syscmd.
maketemp( . . . XXXXX . . . )
Replaces XXXXX in its argument with
the current process ID number.
m4exit(value) Exits from m4 immediately,
returning the specified exit value
(the default is 0).
m4wrap(lastmacro) Runs lastmacro after reading the
end-of-file character. For
example: "m4wrap(`cleanup()')"
runs the "cleanup" macro at the end
of m4.
errprint(message) Includes message on the diagnostic
output file.
dumpdef([name . . . ])
Writes to standard output the
current names and definitions for
the named items or for all if no
arguments are provided.
traceon(macro) Turns on tracing for macro. If
none is named, tracing is turned on
for all macros.
traceoff(macro . . . )
Turns off trace globally and for
any macro specified. Macros spe-
cifically traced by traceon can be
untraced only by specific calls to
traceoff.
FLAGS
-Bnum Makes num the size of the push-back and
parameter collection buffers (the default
is 4096).
-e Operates interactively. Interrupts are
ignored and the output is not buffered.
-Hnum Makes num the size of the symbol table hash
array (the default is 199). The size must
be a prime number.
-s Enables the line sync output for the C pre-
processor (#line . . . ).
-Snum Makes num the size of the call stack (the
default is 800 slots). Macros take three
slots, and nonmacro arguments take one.
-Tnum Makes num the size of the token buffer (the
default is 512 bytes).
The preceding flags must appear before any file names and
before any -D or -U flags.
-Dname[=val] Define name as val. If val is not speci-
fied, name becomes null.
-Uname Undefines a name previously defined with
the -D flag.
EXAMPLE
To preprocess a C language program with m4 and compile
it:
m4 prog.m4 >prog.c
cc prog.c
RELATED INFORMATION
The following commands: "cc" and "cpp."
The "Overview of International Character Support" in Man-
aging the AIX Operating System.