m4 - Preprocesses files, expanding macro definitions
m4 [-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.
Interfaces documented on this reference page conform to
industry standards as follows:
m4: XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
[Tru64 UNIX] Makes number the size of the push-back and
parameter collection buffers (the default is 4096).
[Tru64 UNIX] Operates interactively. 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 operands.
[XPG4-UNIX] Pathname of a file to be processed. If file
is omitted, standard input is used. [XPG4-UNIX] Read
standard input.
[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 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 literally; 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 [Toc] [Back]
[XPG4-UNIX] The m4 command contains the following builtin
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
character becomes the end-quote string. With two
arguments, the first argument becomes the beginquote
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 disabled.
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 numerical 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 argument). Text can
be undiverted into another diversion. Undiverting
discards the diverted text. [XPG4-UNIX] Returns
the value of the current output stream.
[XPG4-UNIX] Reads and discards 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 arguments, 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 characters 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 inaccessible.
[XPG4-UNIX] Runs the specified operating
system command. 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
argument 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-ofFile
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 specified. Macros specifically traced by
traceon can be untraced only by specific calls to
traceoff.
[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.
To preprocess a C language program with m4 and compile it,
enter: m4 prog.m4 >prog.c cc prog.c
ENVIRONMENT VARIABLES [Toc] [Back] 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 corresponding value from the
default locale is used. If any of the internationalization
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 internationalization 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 diagnostic messages written
to standard error. [XPG4-UNIX] Determines the location
of message catalogues for the processing of LC_MESSAGES.
Commands: c89(1), cc(1), cpp(1)
Standards: standards(5)
m4(1)
[ Back ] |
