# m4

## PROLOG



           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.
    


## NAME



           m4 — macro processor
    


## SYNOPSIS



           m4 **[** -s**] [** -D _name_**[** =_val_**]]**... **[** -U _name_**]**... _file_...
    


## DESCRIPTION



           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.
    


## OPTIONS



           The _m4_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _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_.
    


## OPERANDS



           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.
    


## STDIN



           The standard input shall be a text file that is used if no _file_
           operand is given, or if it is **'-'**.
    


## INPUT FILES



           The input file named by the _file_ operand shall be a text file.
    


## ENVIRONMENT VARIABLES



           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‐2017, _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_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           The standard output shall be the same as the input files, after
           being processed for macro expansion.
    


## STDERR



           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.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           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 shall be the exit code. If no argument is
                     specified, the exit code shall be zero. It shall be an
                     error to specify an argument containing any non-numeric
                     characters. If the first argument is zero or no argument
                     is specified, and an error has previously occurred (for
                     example, a _file_ operand that could not be opened), it is
                     unspecified whether the exit status is zero or non-zero.
    
           **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 defining text shall be as if it were the resulting
                     pathname after a successful call to the _mkstemp_()
                     function defined in the System Interfaces volume of
                     POSIX.1‐2017 called with the first argument to the macro
                     invocation. If a file is created, that file shall be
                     closed.  If a file could not be created, the _m4_ utility
                     shall write a diagnostic message to standard error and
                     shall continue processing input but its final exit
                     status shall be non-zero; 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.
    


## EXIT STATUS



           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.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           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.
    


## EXAMPLES



           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
    


## RATIONALE



           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.
    


## FUTURE DIRECTIONS



           None.
    


* * *