|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
M4(1P) POSIX Programmer's Manual M4(1P)
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the
corresponding Linux manual page for details of Linux behavior), or
the interface may not be implemented on Linux.
m4 — macro processor
m4 [−s] [−D name[=val]]... [−U name]... file...
The m4 utility is a macro processor that shall read one or more text
files, process them according to their included macro statements, and
write the results to standard output.
The m4 utility shall conform to the Base Definitions volume of
POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines, except that
the order of the −D and −U options shall be significant, and options
can be interspersed with operands.
The following options shall be supported:
−s Enable line synchronization output for the c99 preprocessor
phase (that is, #line directives).
−D name[=val]
Define name to val or to null if =val is omitted.
−U name Undefine name.
The following operand shall be supported:
file A pathname of a text file to be processed. If no file is
given, or if it is '−', the standard input shall be read.
The standard input shall be a text file that is used if no file
operand is given, or if it is '−'.
The input file named by the file operand shall be a text file.
The following environment variables shall affect the execution of m4:
LANG Provide a default value for the internationalization
variables that are unset or null. (See the Base Definitions
volume of POSIX.1‐2008, Section 8.2, Internationalization
Variables for the precedence of internationalization
variables used to determine the values of locale
categories.)
LC_ALL If set to a non-empty string value, override the values of
all the other internationalization variables.
LC_CTYPE Determine 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 and input
files).
LC_MESSAGES
Determine the locale that should be used to affect the
format and contents of diagnostic messages written to
standard error.
NLSPATH Determine the location of message catalogs for the
processing of LC_MESSAGES.
Default.
The standard output shall be the same as the input files, after being
processed for macro expansion.
The standard error shall be used to display strings with the errprint
macro, macro tracing enabled by the traceon macro, the defined text
for macros written by the dumpdef macro, or for diagnostic messages.
None.
The m4 utility shall compare each token from the input against the
set of built-in and user-defined macros. If the token matches the
name of a macro, then the token shall be replaced by the macro's
defining text, if any, and rescanned for matching macro names. Once
no portion of the token matches the name of a macro, it shall be
written to standard output. Macros may have arguments, in which case
the arguments shall be substituted into the defining text before it
is rescanned.
Macro calls have the form:
name(arg1, arg2, ..., argn)
Macro names shall consist of letters, digits, and underscores, where
the first character is not a digit. Tokens not of this form shall not
be treated as macros.
The application shall ensure that the <left-parenthesis> immediately
follows the name of the macro. If a token matching the name of a
macro is not followed by a <left-parenthesis>, it is handled as a use
of that macro without arguments.
If a macro name is followed by a <left-parenthesis>, its arguments
are the <comma>-separated tokens between the <left-parenthesis> and
the matching <right-parenthesis>. Unquoted white-space characters
preceding each argument shall be ignored. All other characters,
including trailing white-space characters, are retained. <comma>
characters enclosed between <left-parenthesis> and <right-
parenthesis> characters do not delimit arguments.
Arguments are positionally defined and referenced. The string "$1" in
the defining text shall be replaced by the first argument. Systems
shall support at least nine arguments; only the first nine can be
referenced, using the strings "$1" to "$9", inclusive. The string
"$0" is replaced with the name of the macro. The string "$#" is
replaced by the number of arguments as a string. The string "$*" is
replaced by a list of all of the arguments, separated by <comma>
characters. The string "$@" is replaced by a list of all of the
arguments separated by <comma> characters, and each argument is
quoted using the current left and right quoting strings. The string
"${" produces unspecified behavior.
If fewer arguments are supplied than are in the macro definition, the
omitted arguments are taken to be null. It is not an error if more
arguments are supplied than are in the macro definition.
No special meaning is given to any characters enclosed between
matching left and right quoting strings, but the quoting strings are
themselves discarded. By default, the left quoting string consists of
a grave accent (backquote) and the right quoting string consists of
an acute accent (single-quote); see also the changequote macro.
Comments are written but not scanned for matching macro names; by
default, the begin-comment string consists of the <number-sign>
character and the end-comment string consists of a <newline>. See
also the changecom and dnl macros.
The m4 utility shall make available the following built-in macros.
They can be redefined, but once this is done the original meaning is
lost. Their values shall be null unless otherwise stated. In the
descriptions below, the term defining text refers to the value of the
macro: the second argument to the define macro, among other things.
Except for the first argument to the eval macro, all numeric
arguments to built-in macros shall be interpreted as decimal values.
The string values produced as the defining text of the decr, divnum,
incr, index, len, and sysval built-in macros shall be in the form of
a decimal-constant as defined in the C language.
changecom The changecom macro shall set the begin-comment and end-
comment strings. With no arguments, the comment mechanism
shall be disabled. With a single non-null argument, that
argument shall become the begin-comment and the <newline>
shall become the end-comment string. With two non-null
arguments, the first argument shall become the begin-
comment string and the second argument shall become the
end-comment string. The behavior is unspecified if either
argument is provided but null. Systems shall support
comment strings of at least five characters.
changequote
The changequote macro shall set the begin-quote and end-
quote strings. With no arguments, the quote strings shall
be set to the default values (that is, `'). The behavior is
unspecified if there is a single argument or either
argument is null. With two non-null arguments, the first
argument shall become the begin-quote string and the second
argument shall become the end-quote string. Systems shall
support quote strings of at least five characters.
decr The defining text of the decr macro shall be its first
argument decremented by 1. It shall be an error to specify
an argument containing any non-numeric characters. The
behavior is unspecified if decr is not immediately followed
by a <left-parenthesis>.
define The second argument shall become the defining text of the
macro whose name is the first argument. It is unspecified
whether the define macro deletes all prior definitions of
the macro named by its first argument or preserves all but
the current definition of the macro. The behavior is
unspecified if define is not immediately followed by a
<left-parenthesis>.
defn The defining text of the defn macro shall be the quoted
definition (using the current quoting strings) of its
arguments. The behavior is unspecified if defn is not
immediately followed by a <left-parenthesis>.
divert The m4 utility maintains nine temporary buffers, numbered 1
to 9, inclusive. When the last of the input has been
processed, any output that has been placed in these buffers
shall be written to standard output in buffer-numerical
order. The divert macro shall divert future output to the
buffer specified by its argument. Specifying no argument or
an argument of 0 shall resume the normal output process.
Output diverted to a stream with a negative number shall be
discarded. Behavior is implementation-defined if a stream
number larger than 9 is specified. It shall be an error to
specify an argument containing any non-numeric characters.
divnum The defining text of the divnum macro shall be the number
of the current output stream as a string.
dnl The dnl macro shall cause m4 to discard all input
characters up to and including the next <newline>.
dumpdef The dumpdef macro shall write the defined text to standard
error for each of the macros specified as arguments, or, if
no arguments are specified, for all macros.
errprint The errprint macro shall write its arguments to standard
error. The behavior is unspecified if errprint is not
immediately followed by a <left-parenthesis>.
eval The eval macro shall evaluate its first argument as an
arithmetic expression, using signed integer arithmetic with
at least 32-bit precision. At least the following C-
language operators shall be supported, with precedence,
associativity, and behavior as described in Section
1.1.2.1, Arithmetic Precision and Operations:
()
unary +
unary −
~
!
binary *
/
%
binary +
binary −
<<
>>
<
<=
>
>=
==
!=
binary &
^
|
&&
||
Systems shall support octal and hexadecimal numbers as in
the ISO C standard. The second argument, if specified,
shall set the radix for the result; if the argument is
blank or unspecified, the default is 10. Behavior is
unspecified if the radix falls outside the range 2 to 36,
inclusive. The third argument, if specified, sets the
minimum number of digits in the result. Behavior is
unspecified if the third argument is less than zero. It
shall be an error to specify the second or third argument
containing any non-numeric characters. The behavior is
unspecified if eval is not immediately followed by a <left-
parenthesis>.
ifdef If the first argument to the ifdef macro is defined, the
defining text shall be the second argument. Otherwise, the
defining text shall be the third argument, if specified, or
the null string, if not. The behavior is unspecified if
ifdef is not immediately followed by a <left-parenthesis>.
ifelse The ifelse macro takes three or more arguments. If the
first two arguments compare as equal strings (after macro
expansion of both arguments), the defining text shall be
the third argument. If the first two arguments do not
compare as equal strings and there are three arguments, the
defining text shall be null. If the first two arguments do
not compare as equal strings and there are four or five
arguments, the defining text shall be the fourth argument.
If the first two arguments do not compare as equal strings
and there are six or more arguments, the first three
arguments shall be discarded and processing shall restart
with the remaining arguments. The behavior is unspecified
if ifelse is not immediately followed by a <left-
parenthesis>.
include The defining text for the include macro shall be the
contents of the file named by the first argument. It shall
be an error if the file cannot be read. The behavior is
unspecified if include is not immediately followed by a
<left-parenthesis>.
incr The defining text of the incr macro shall be its first
argument incremented by 1. It shall be an error to specify
an argument containing any non-numeric characters. The
behavior is unspecified if incr is not immediately followed
by a <left-parenthesis>.
index The defining text of the index macro shall be the first
character position (as a string) in the first argument
where a string matching the second argument begins (zero
origin), or −1 if the second argument does not occur. The
behavior is unspecified if index is not immediately
followed by a <left-parenthesis>.
len The defining text of the len macro shall be the length (as
a string) of the first argument. The behavior is
unspecified if len is not immediately followed by a <left-
parenthesis>.
m4exit Exit from the m4 utility. If the first argument is
specified, it is the exit code. The default is zero. It
shall be an error to specify an argument containing any
non-numeric characters.
m4wrap The first argument shall be processed when EOF is reached.
If the m4wrap macro is used multiple times, the arguments
specified shall be processed in the order in which the
m4wrap macros were processed. The behavior is unspecified
if m4wrap is not immediately followed by a <left-
parenthesis>.
maketemp The defining text shall be the first argument, with any
trailing 'X' characters replaced with the current process
ID as a string. The behavior is unspecified if maketemp is
not immediately followed by a <left-parenthesis>.
mkstemp The first argument shall be taken as a template for
creating an empty file, with trailing 'X' characters
replaced with characters from the portable filename
character set. The behavior is unspecified if the first
argument does not end in at least six 'X' characters. If a
temporary file is successfully created, then the defining
text of the macro shall be the name of the new file. The
user ID of the file shall be set to the effective user ID
of the process. The group ID of the file shall be set to
the group ID of the file's parent directory or to the
effective group ID of the process. The file access
permission bits are set such that only the owner can both
read and write the file, regardless of the current umask of
the process. If a file could not be created, the defining
text of the macro shall be the empty string. The behavior
is unspecified if mkstemp is not immediately followed by a
<left-parenthesis>.
popdef The popdef macro shall delete the current definition of its
arguments, replacing that definition with the previous one.
If there is no previous definition, the macro is undefined.
The behavior is unspecified if popdef is not immediately
followed by a <left-parenthesis>.
pushdef The pushdef macro shall be equivalent to the define macro
with the exception that it shall preserve any current
definition for future retrieval using the popdef macro. The
behavior is unspecified if pushdef is not immediately
followed by a <left-parenthesis>.
shift The defining text for the shift macro shall be a comma-
separated list of its arguments except the first one. Each
argument shall be quoted using the current quoting strings.
The behavior is unspecified if shift is not immediately
followed by a <left-parenthesis>.
sinclude The sinclude macro shall be equivalent to the include
macro, except that it shall not be an error if the file is
inaccessible. The behavior is unspecified if sinclude is
not immediately followed by a <left-parenthesis>.
substr The defining text for the substr macro shall be the
substring of the first argument beginning at the zero-
offset character position specified by the second argument.
The third argument, if specified, shall be the number of
characters to select; if not specified, the characters from
the starting point to the end of the first argument shall
become the defining text. It shall not be an error to
specify a starting point beyond the end of the first
argument and the defining text shall be null. It shall be
an error to specify an argument containing any non-numeric
characters. The behavior is unspecified if substr is not
immediately followed by a <left-parenthesis>.
syscmd The syscmd macro shall interpret its first argument as a
shell command line. The defining text shall be the string
result of that command. The string result shall not be
rescanned for macros while setting the defining text. No
output redirection shall be performed by the m4 utility.
The exit status value from the command can be retrieved
using the sysval macro. The behavior is unspecified if
syscmd is not immediately followed by a <left-parenthesis>.
sysval The defining text of the sysval macro shall be the exit
value of the utility last invoked by the syscmd macro (as a
string).
traceon The traceon macro shall enable tracing for the macros
specified as arguments, or, if no arguments are specified,
for all macros. The trace output shall be written to
standard error in an unspecified format.
traceoff The traceoff macro shall disable tracing for the macros
specified as arguments, or, if no arguments are specified,
for all macros.
translit The defining text of the translit macro shall be the first
argument with every character that occurs in the second
argument replaced with the corresponding character from the
third argument. If no replacement character is specified
for some source character because the second argument is
longer than the third argument, that character shall be
deleted from the first argument in translit's defining
text. The behavior is unspecified if the '−' character
appears within the second or third argument anywhere
besides the first or last character. The behavior is
unspecified if the same character appears more than once in
the second argument. The behavior is unspecified if
translit is not immediately followed by a <left-
parenthesis>.
undefine The undefine macro shall delete all definitions (including
those preserved using the pushdef macro) of the macros
named by its arguments. The behavior is unspecified if
undefine is not immediately followed by a <left-
parenthesis>.
undivert The undivert macro shall cause immediate output of any text
in temporary buffers named as arguments, or all temporary
buffers if no arguments are specified. Buffers can be
undiverted into other temporary buffers. Undiverting shall
discard the contents of the temporary buffer. The behavior
is unspecified if an argument contains any non-numeric
characters.
The following exit values shall be returned:
0 Successful completion.
>0 An error occurred
If the m4exit macro is used, the exit value can be specified by the
input file.
Default.
The following sections are informative.
The defn macro is useful for renaming macros, especially built-ins.
Since eval defers to the ISO C standard, some operations have
undefined behavior. In some implementations, division or remainder by
zero cause a fatal signal, even if the division occurs on the short-
circuited branch of "&&" or "||". Any operation that overflows in
signed arithmetic produces undefined behavior. Likewise, using the
shift operators with a shift amount that is not positive and smaller
than the precision is undefined, as is shifting a negative number to
the right. Historically, not all implementations obeyed C-language
precedence rules: '~' and '!' were lower than '=='; '==' and '!='
were not lower than '<'; and '|' was not lower than '^'; the liberal
use of "()" can force the desired precedence even with these non-
compliant implementations. Furthermore, some traditional
implementations treated '^' as an exponentiation operator, although
most implementations now use "**" as an extension for this purpose.
When a macro has been multiply defined via the pushdef macro, it is
unspecified whether the define macro will alter only the most recent
definition (as though by popdef and pushdef), or replace the entire
stack of definitions with a single definition (as though by undefine
and pushdef). An application desiring particular behavior for the
define macro in this case can redefine it accordingly.
Applications should use the mkstemp macro instead of the obsolescent
maketemp macro for creating temporary 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
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
Historic System V-based behavior treated "${" in a macro definition
as two literal characters. However, this sequence is left unspecified
so that implementations may offer extensions such as "${11}" meaning
the eleventh positional parameter. Macros can still be defined with
appropriate uses of nested quoting to result in a literal "${" in the
output after rescanning removes the nested quotes.
In the translit built-in, historic System V-based behavior treated
'−' as a literal; GNU behavior treats it as a range. This version of
the standard allows either behavior.
None.
c99(1p)
The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
Variables, Section 12.2, Utility Syntax Guidelines
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The Open
Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open
Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
applied.) In the event of any discrepancy between this version and
the original IEEE and The Open Group Standard, the original IEEE and
The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the
source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 M4(1P)