Table of Contents
m4 - macro processor (DEVELOPMENT)
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 IEEE Std 1003.1-2001, Section
12.2, Utility Syntax Guidelines, except that the order of the -D and -U options
shall be significant.
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 IEEE Std 1003.1-2001,
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 <blank>s and <newline>s preceding each
argument shall be ignored. All other characters, including trailing <blank>s
and <newline>s, are retained. Commas enclosed between left 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 commas. The string "$@"
is replaced by a list of all of the arguments separated by commas, and
each argument is quoted using the current left and right quoting strings.
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 ( ’‘’ ) and the right quoting string consists
of an acute accent ( ’" ); 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 argument, that argument shall become the
begin-comment string and the <newline> shall become the end-comment string.
With two arguments, the first argument shall become the begin-comment string
and the second argument shall become the end-comment string. 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, ‘’). With a
single argument, that argument shall become the begin-quote string and the
<newline> shall become the end-quote string. With two 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.
- define
- The second argument shall become the defining
text of the macro whose name is the first argument.
- defn
- The defining text
of the defn macro shall be the quoted definition (using the current quoting
strings) of its arguments.
- 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 other than 0 to 9 shall be discarded. 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.
- eval
- The eval
macro shall evaluate its first argument as an arithmetic expression, using
32-bit signed integer arithmetic. All of the C-language operators shall be
supported, except for:
[]
->
++
--
(type)
unary *
sizeof,
.
?:
unary &
and all assignment operators. It shall be an error to specify any of these
operators. Precedence and associativity shall be as in the ISO C standard.
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;
the default is 10. The third argument, if specified, sets the minimum number
of digits in the result. It shall be an error to specify the second or third
argument containing any non-numeric characters.
- 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.
- 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.
- 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.
- 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.
- 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.
- len
- The defining
text of the len macro shall be the length (as a string) of the first argument.
- 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.
- maketemp
- The defining text shall be the
first argument, with any trailing ’X’ characters replaced with the current
process ID as a string.
- 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.
- 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.
- shift
- The defining text for the shift macro shall be all
of its arguments except for the first one.
- sinclude
- The sinclude macro shall
be equivalent to the include macro, except that it shall not be an error
if the file is inaccessible.
- 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.
- 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. No output redirection shall be performed by the m4 utility. The
exit status value from the command can be retrieved using the sysval macro.
- 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.
- undefine
- The undefine macro shall delete all definitions
(including those preserved using the pushdef macro) of the macros named
by its arguments.
- 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.
It shall be an error to specify an argument containing any non-numeric characters.
The following exit values shall be returned:
- 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.
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
None.
None.
c99
Portions of this
text are reprinted and reproduced in electronic form from IEEE Std 1003.1,
2003 Edition, Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright
(C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
Inc and The Open Group. 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.opengroup.org/unix/online.html
.
Table of Contents