M4(1,C) AIX Commands Reference M4(1,C)
-------------------------------------------------------------------------------
m4
PURPOSE
Preprocesses files, expanding macro definitions.
SYNTAX
+--------+ +- -B4096 -+ +- -H199 -+ +- -S100 -+ +- -T512 -+
m4 ---| +----+ |---| |---| |---| |---| |--->
+-| -e |-+ +- -Bnum --+ +- -Hnum -+ +- -Snum -+ +- -Tnum -+
^| -s ||
|+----+|
+------+
+------------------------+ +----------+ +--------+
>---| +-- ="" ---+ |---| |---| |---|
A +- -D name -|1 |-+ +- -Uname -+ | +- file -+
| +- =value -+ | ^ |
+-------------------------------------------+ +------+
Note: This command does not have MBCS support.
DESCRIPTION
The m4 command is a macro processor used as a preprocessor 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 arguments. Macro names consist of ASCII alphabetic letters,
digits, and the underscore character (_). Extended characters are not allowed
in macro names. The first character cannot be a digit.
While collecting arguments, m4 ignores unquoted leading blanks, tabs, and
new-line characters. Use single quotation 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
definition, m4 considers the trailing arguments in the definition 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
Processed November 8, 1990 M4(1,C) 1
M4(1,C) AIX Commands Reference M4(1,C)
literally; they do not need an escape character 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 replaces missing arguments. The number of
arguments replaces "$#". A comma-separated list of
all arguments 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 saves
any previous definition.
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 returns 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 subsequently be performed.
changequote(L,R) Changes quote symbols to L and R. The symbols can be
up to five bytes long. changequote without arguments
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
character. With two arguments, both markers are
Processed November 8, 1990 M4(1,C) 2
M4(1,C) AIX Commands Reference M4(1,C)
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. Initially, 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
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
next new-line character.
ifelse([string1,string2,true,[false]]...)
If string1 and string2 are the same, the value is
true. If they are not and if there are more than
four arguments, m4 repeats the process with the
additional arguments (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 parentheses. Octal and hex numbers
can be specified as in C. num1 specifies 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 character.
index(s1,s2) Returns the position in the string s1 where the
string s2 begins (zero origin), or -1 if the second
parameter does not occur.
Processed November 8, 1990 M4(1,C) 3
M4(1,C) AIX Commands Reference M4(1,C)
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 substring. 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
abbreviations 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 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 specifically 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. If the -Bnum flag is not used, the size is 4096.
Processed November 8, 1990 M4(1,C) 4
(1,C) AIX Commands Reference (1,C)
-e Operates interactively. Interrupts are ignored and the output
is not buffered.
-Hnum Makes num the size of the symbol table hash array. The size
must be a prime number. If the -Hnum flag is not used, the size
is 199.
-s Enables the line sync output for the C preprocessor (#line...).
-Snum Makes num the size of the call stack. Macros take three slots,
and nonmacro arguments take one. If the -Snum flag is not used,
the size is 800 slots.
-Tnum Makes num the size of the token buffer. If the -Tnum flag is
not used, the size 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 specified, 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
See the following commands: "cc" and "cpp."
See "Introduction to International Character Support" in Managing the AIX
Operating System.
Processed November 8, 1990 (1,C) 5