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)

PROLOG         top

       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         top

       m4 — macro processor

SYNOPSIS         top

       m4 [−s] [−D name[=val]]... [−U name]... file...

DESCRIPTION         top

       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         top

       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.

OPERANDS         top

       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         top

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

INPUT FILES         top

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

ENVIRONMENT VARIABLES         top

       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.

ASYNCHRONOUS EVENTS         top

       Default.

STDOUT         top

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

STDERR         top

       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         top

       None.

EXTENDED DESCRIPTION         top

       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.

EXIT STATUS         top

       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         top

       Default.

       The following sections are informative.

APPLICATION USAGE         top

       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         top

       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         top

       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         top

       None.

SEE ALSO         top

       c99(1p)

       The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
       Variables, Section 12.2, Utility Syntax Guidelines

COPYRIGHT         top

       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)