m4(1)m4(1)NAMEm4 - Preprocesses files, expanding macro definitions
SYNOPSISm4 [-Bnumber] [-es] [-Hnumber] [-Snumber] [-Tnumber] [-Dmacro] [=value]
[-Umacro] file... | -
[XPG4-UNIX] The m4 command is a macro processor used as a preprocessor
for C and other languages.
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
m4: XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
OPTIONS
[Tru64 UNIX] Makes number the size of the push-back and parameter col‐
lection buffers (the default is 4096). [Tru64 UNIX] Operates interac‐
tively. Interrupts are ignored and the output is not buffered. [Tru64
UNIX] Makes number the size of the symbol table hash array (the
default is 199). The size must be a prime number.
[XPG4-UNIX] Enables the line sync output for the C preprocessor
(#line...). [Tru64 UNIX] Makes number the size of the call stack (the
default is 800 slots). Macros take three slots, and nonmacro arguments
take one. [Tru64 UNIX] Makes number the size of the token buffer (the
default is 512 bytes). [XPG4-UNIX] Defines macro as value. If value
is not specified, macro becomes null. [XPG4-UNIX] Undefines a built-
in macro or one previously defined with the -D option.
Note
[XPG4-UNIX] The order of options is significant. If used, the -D or
-U options must appear after any other options and before any file op‐
erands.
OPERANDS
[XPG4-UNIX] Pathname of a file to be processed. If file is omitted,
standard input is used. [XPG4-UNIX] Read standard input.
DESCRIPTION
[XPG4-UNIX] You can use m4 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 dash (-) as a filename, the m4 command reads standard
input. It writes the processed macros to standard output.
[XPG4-UNIX] Macro calls follow the form: macro(argument...)
[XPG4-UNIX] The left parenthesis must immediately follow macro. If
the left parenthesis does not follow the name of a defined macro, the
m4 command 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.
[XPG4-UNIX] While collecting arguments, the m4 command ignores
unquoted leading spaces, tabs, and newline characters. Use single
quotes ('') to quote strings. The value of a quoted string is the
string with the quotation marks stripped off.
[XPG4-UNIX] When the m4 command recognizes a macro, it collects argu‐
ments 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 pro‐
ceeds normally during the collection of the arguments. All commas or
right parentheses within the value of a nested call are translated lit‐
erally; they do not need an escape character or quotation marks. After
collecting arguments, the m4 command pushes the value of the macro back
onto the input stream and scans again.
Built-In Macros
[XPG4-UNIX] The m4 command contains the following built-in macros.
You can redefine them, but they will then lose their original meanings.
The values of these macros are null unless otherwise stated:
[XPG4-UNIX] Replaces the macro macro with the value of new_name. The
new_name string can included tokens of 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 macro. The name of the macro is $0.
The null string replaces missing arguments. The number of arguments
replaces $#. A list of all arguments, separated by commas, replaces
$*. The $@ acts like $*, but each argument is quoted with the current
quotation character (see the changequote macro). [XPG4-UNIX] Removes
the definition of macro (including those preserved using the pushdef
macro). [XPG4-UNIX] Returns the quoted definition of macro.
[XPG4-UNIX] If the first argument is defined, the value is the second
argument. Otherwise, the value is the third argument. If there is no
third argument, the value is null.
[Tru64 UNIX] Note that the word unix is predefined.
[XPG4-UNIX] Redefines macro with new_name as in define, but
saves any previous definition. [XPG4-UNIX] Removes the current
definition of macro and returns to the previous definition, if
one existed. [XPG4-UNIX] 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. [XPG4-UNIX] The changequote
macro sets the begin and end symbols. With no arguments, the
quote strings are set to the default values (that is, `', one
grave accent and one apostrophe). With a single argument, that
argument becomes the begin-quote string and the newline charac‐
ter becomes the end-quote string. With two arguments, the first
argument becomes the begin-quote string and the second argument
becomes the end-quote string. The symbols can be up to five
bytes long. [XPG4-UNIX] Changes left and right comment markers
from the default # and newline character to left_comment and
right_comment. With no arguments, the comment mechanism is dis‐
abled. With one argument, the left marker becomes the parameter
and the right marker becomes a newline character. With two
arguments, both markers are affected. Comment markers can be up
to 5 bytes long. [XPG4-UNIX] Changes the current output stream
to stream number. There are 10 output streams, numbered 0 to 9.
The final output is the concatenation of the streams in numeri‐
cal order. Initially, stream zero (0) is the current stream.
The m4 command discards output diverted to a stream other than 0
to 9. [XPG4-UNIX] Causes immediate output of text from the
specified diversions (or all diversions if there is no argu‐
ment). Text can be undiverted into another diversion. Undi‐
verting discards the diverted text. [XPG4-UNIX] Returns the
value of the current output stream. [XPG4-UNIX] Reads and dis‐
cards characters up to and including the next newline character.
[XPG4-UNIX] If string1 and string2 are the same, then the value
is true. If they are not and if there are more than four argu‐
ments, m4 repeats the process with the additional arguments (4,
5, 6, and so on). Otherwise, the value is either false or null
if you provide no value for false. [XPG4-UNIX] Returns the
value of its argument incremented by 1. [XPG4-UNIX] Returns
the value of its argument decreased by 1.
"eval(expression[,number1[,number2]])"
[XPG4-UNIX] Evaluates its first argument as an arithmetic
expression, using 32-bit (long) arithmetic. The operators you
can use include +, -, *, /, %, ^ (exponentiation), bitwise &, |,
~, and ^ relationals, and parentheses.
[XPG4-UNIX] Octal and hex numbers can be specified as in C. The
optional number1 specifies the radix for the result of the
expression. The default radix is 10. The optional number2
specifies the minimum number of digits in the result. The
default is 1. [XPG4-UNIX] Returns the number of bytes in
string. [Tru64 UNIX] Returns the number of displayable charac‐
ters in string; that is, 2-byte extended characters are counted
as one displayable character. [XPG4-UNIX] Returns the first
position in string1, where string2 begins (zero origin), or -1
if the second argument does not occur. [XPG4-UNIX] Returns a
substring of string. The beginning of the substring is selected
with position, and number indicates the length of the substring.
Without number, the substring includes everything to the end of
the first string. [XPG4-UNIX] Transliterates the characters in
string from the set given by from to the set given by to. No
abbreviations are permitted. 2-byte extended characters are
correctly mapped into the corresponding replacement characters.
[XPG4-UNIX] Returns the contents of file or displays an error
message if it cannot access the file. [XPG4-UNIX] Returns the
contents of file, but it gives no error message if file is inac‐
cessible. [XPG4-UNIX] Runs the specified operating system com‐
mand. No value is returned, but sysval can be used to retrieve
the exit value. [XPG4-UNIX] Returns the return code from the
last call to syscmd. [XPG4-UNIX] Replaces xxxxx in its argu‐
ment with the current process ID number where xxxxx represents
any number of numeric or alphanumeric characters.
[XPG4-UNIX] Exits from m4 immediately, returning the specified
exit value (the default is zero (0)). [XPG4-UNIX] Sets or
resets last_macro, which is run after reading the End-of-File
character. For example: m4wrap(`cleanup()') sets the cleanup
macro at the end of m4. [XPG4-UNIX] Includes message on the
diagnostic output file (standard error). [XPG4-UNIX] Writes to
standard output the current names and definitions for the named
items or for all items if no arguments are provided.
[XPG4-UNIX] Turns on tracing for macro. If none is named,
tracing is turned on for all macro expansions.
[XPG4-UNIX] Turns off trace globally and for any macro speci‐
fied. Macros specifically traced by traceon can be untraced
only by specific calls to traceoff.
EXIT STATUS
[XPG4-UNIX] Successful completion. [XPG4-UNIX] An error occurred.
[XPG4-UNIX] If you use the m4exit macro, the input file can specify
the exit value.
EXAMPLES
To preprocess a C language program with m4 and compile it, enter: m4
prog.m4 >prog.c cc prog.c
ENVIRONMENT VARIABLES
The following environment variables affect the execution of m4:
[XPG4-UNIX] Provides a default value for the internationalization
variables that are unset or null. If LANG is unset or null, the corre‐
sponding value from the default locale is used. If any of the interna‐
tionalization variables contain an invalid setting, the utility behaves
as if none of the variables had been defined. [XPG4-UNIX] If set to a
non-empty string value, overrides the values of all the other interna‐
tionalization variables. [XPG4-UNIX] Determines the locale for the
interpretation of sequences of bytes of text data as characters (for
example, single-byte as opposed to multi-byte characters in arguments).
[XPG4-UNIX] Determines the locale for the format and contents of diag‐
nostic messages written to standard error. [XPG4-UNIX] Determines the
location of message catalogues for the processing of LC_MESSAGES.
SEE ALSO
Commands: c89(1), cc(1), cpp(1)
Standards: standards(5)m4(1)