User Commands m4(1)
NAME
m4 - macro processor
SYNOPSIS
/usr/bin/m4 [-e] [-s] [-B int] [-H int] [-S int]
[-T int] [-Dname [=val] ... [-U name] ... [file]...
/usr/xpg4/bin/m4 [-e] [-s] [-B int] [-H int] [-S int]
[-T int] [-Dname [...=val] [-U name] ... [file]...
DESCRIPTION
The m4 utility is a macro processor intended as a front end
for C, assembler, and other languages. Each of the argument
files is processed in order. If there are no files, or if a
file is -, the standard input is read. The processed text is
written on the standard output. Note: m4 cannot include more
than nine nested files and writes a diagnostic message if
that number is exceeded.
Macro Syntax
Macro calls have the form:
name(arg1,arg2, ..., argn)
The open parenthesis character, (, 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
alphanumeric characters 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.
Macro Processing
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 NUL. 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 argument collection, the
value of the macro is pushed back onto the input stream and
SunOS 5.11 Last change: 3 Jul 2007 1
User Commands m4(1)
rescanned.
OPTIONS
The options and their effects are as follows:
-Bint Changes the size of the push-back and argument col-
lection buffers from the default of 4,096.
-e Operates interactively. Interrupts are ignored and
the output is unbuffered.
-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 100slots. Macros take three slots, and non-macro
arguments take one.
-Tint Changes the size of the token buffer from the
default of 512bytes.
To be effective, the above flags must appear before any file
names and before any -D or -U flags:
-D name[=val] Defines name to val or to NUL in val's
absence.
-Uname Undefines name.
OPERANDS
The following operand is supported:
file A path name of a text file to be processed. If no
file is given, or if it is -, the standard input is
read.
USAGE
The m4 utility makes available the following built-in mac-
ros. These macros can be redefined, but once this is done
SunOS 5.11 Last change: 3 Jul 2007 2
User Commands m4(1)
the original meaning is lost. Their values are NUL unless
otherwise stated.
changequote Change quote symbols to the first and second
arguments. The symbols can be up to five
characters long. changequote without argu-
ments restores the original values (that is,
`').
changecom Change left and right comment markers from
the default # and NEWLINE. With no arguments,
the comment mechanism is effectively dis-
abled. With one argument, the left marker
becomes the argument and the right marker
becomes NEWLINE. With two arguments, both
markers are affected. Comment markers can be
up to five characters long.
decr Returns the value of its argument decremented
by 1.
define The second argument is installed as the value
of the macro whose name is the first argu-
ment. Each occurrence of $n in the replace-
ment text, where n is a digit, is replaced by
the n-th 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).
defn Returns the quoted definition of its
argument(s). It is useful for renaming mac-
ros, 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
(digit-string) argument. Output diverted to a
stream other than 0 through 9 is discarded.
SunOS 5.11 Last change: 3 Jul 2007 3
User Commands m4(1)
divnum Returns the value of the current output
stream.
dnl Reads and discards characters up to and
including the next NEWLINE.
dumpdef Prints current names and definitions, for the
named items, or for all if no arguments are
given.
errprint Prints its argument on the diagnostic output
file.
ifdef If the first argument is defined, the value
is the second argument, otherwise the third.
If there is no third argument, the value is
NUL. The word unix is predefined.
ifelse This macro has 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 argu-
ments, 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,
NUL.
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 digit-string as a
decimal number.
index Returns the position in its first argument
where the second argument begins (zero ori-
gin), or -1 if the second argument does not
occur.
len Returns the number of characters in its argu-
ment.
SunOS 5.11 Last change: 3 Jul 2007 4
User Commands m4(1)
m4exit This macro causes immediate exit from m4.
Argument 1, if given, is the exit code; the
default is 0.
m4wrap Argument 1 is pushed back at final EOF. Exam-
ple: m4wrap(`cleanup()')
maketemp Fills in a string of "X" characters in its
argument with the current process ID.
popdef Removes current definition of its
argument(s), exposing the previous one, if
any.
pushdef Like define, but saves any previous defini-
tion.
shift Returns all but its 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
be performed.
sinclude This macro is identical to include, except
that it says nothing if the file is inacces-
sible.
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 sub-
string. A missing third argument is taken to
be large enough to extend to the end of the
first string.
syscmd This macro executes the command given in the
first argument. No value is returned.
sysval This macro is the return code from the last
call to syscmd.
SunOS 5.11 Last change: 3 Jul 2007 5
User Commands m4(1)
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.
traceon This macro with no arguments, turns on trac-
ing for all macros (including built-ins).
Otherwise, turns on tracing for named macros.
traceoff Turns off trace globally and for any macros
specified.
undefine Removes the definition of the macro named in
its argument.
undivert This macro causes immediate output of text
from diversions named as arguments, or all
diversions if no argument. Text can be
undiverted into another diversion. Undivert-
ing discards the diverted text.
/usr/bin/m4
eval Evaluates its argument as an arithmetic expression,
using 32-bit signed-integer arithmetic. The follow-
ing operators are supported: parentheses, unary -,
unary ], !, ~, *, /, %, ], -, relationals, bitwise
&, , &&, and . Octal and hex numbers can be
specified as in C. The second argument specifies the
radix for the result; the default is 10. The third
argument can be used to specify the minimum number
of digits in the result.
/usr/xpg4/bin/m4
eval Evaluates its argument as an arithmetic expression,
using 32-bit signed-integer arithmetic. The follow-
ing operators are supported: parentheses, unary -,
unary ], !, ~, *, /, %, ], -, <<, >>, relationals,
bitwise &, , &&, and . Precedence and associa-
tivity are as in C. Octal and hex numbers can also
be specified as in C. The second argument specifies
the radix for the result; the default is 10. The
third argument can be used to specify the minimum
number of digits in the result.
SunOS 5.11 Last change: 3 Jul 2007 6
User Commands m4(1)
EXAMPLES
Example 1 Examples of m4 files
If the file m4src contains the lines:
The value of `VER' is "VER".
ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
ifelse(VER, 1, ``VER'' is `VER'.)
ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
end
then the command:
m4 m4src
or the command:
m4 -U VER m4src
produces the output:
The value of VER is "VER".
VER is not defined.
VER is not 2.
end
The command:
m4 -D VER m4src
SunOS 5.11 Last change: 3 Jul 2007 7
User Commands m4(1)
produces the output:
The value of VER is "".
VER is defined to be .
VER is not 2.
end
The command:
m4 -D VER=1 m4src
produces the output:
The value of VER is "1".
VER is defined to be 1.
VER is 1.
VER is not 2.
end
The command:
m4 -D VER=2 m4src
produces the output:
The value of VER is "2".
VER is defined to be 2.
VER is 2.
end
SunOS 5.11 Last change: 3 Jul 2007 8
User Commands m4(1)
ENVIRONMENT VARIABLES
See environ(5) for descriptions of the following environment
variables that affect the execution of m4: LANG, LCAL,
LCTYPE, LCMESAGES, and NLSPATH.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred
If the m4exit macro is used, the exit value can be specified
by the input file.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
/usr/bin/m4
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
/usr/xpg4/bin/m4
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWxcu4
Interface Stability Standard
SEE ALSO
as(1), attributes(5), environ(5), standards(5)
SunOS 5.11 Last change: 3 Jul 2007 9
|
