M4(1)                      POSIX Programmer's Manual                     M4(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       m4 -- macro processor

SSYYNNOOPPSSIISS
       m4 [[-s]] [[-D _n_a_m_e[[=_v_a_l]]]]... [[-U _n_a_m_e]]... _f_i_l_e...

DDEESSCCRRIIPPTTIIOONN
       The _m_4 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.

OOPPTTIIOONNSS
       The _m_4 utility shall conform to the Base Definitions volume of
       POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, except that the
       order of the --DD and --UU options shall be significant, and options can be
       interspersed with operands.

       The following options shall be supported:

       --ss        Enable line synchronization output for the _c_9_9 preprocessor
                 phase (that is, ##lliinnee directives).

       --DD _n_a_m_e[[=_v_a_l]]
                 Define _n_a_m_e to _v_a_l or to null if =_v_a_l is omitted.

       --UU _n_a_m_e   Undefine _n_a_m_e.

OOPPEERRAANNDDSS
       The following operand shall be supported:

       _f_i_l_e      A pathname of a text file to be processed. If no _f_i_l_e is
                 given, or if it is ''--'', the standard input shall be read.

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

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

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _m_4:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

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

SSTTDDEERRRR
       The standard error shall be used to display strings with the eerrrrpprriinntt
       macro, macro tracing enabled by the ttrraacceeoonn macro, the defined text for
       macros written by the dduummppddeeff macro, or for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       The _m_4 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:

           _n_a_m_e(_a_r_g_1, _a_r_g_2, ..., _a_r_g_n)

       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 ""$$11"" 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 ""$$11"" to ""$$99"", inclusive. The string ""$$00""
       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 cchhaannggeeqquuoottee 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 cchhaannggeeccoomm and ddnnll macros.

       The _m_4 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 _d_e_f_i_n_i_n_g _t_e_x_t refers to the value of the macro: the
       second argument to the ddeeffiinnee macro, among other things. Except for the
       first argument to the eevvaall macro, all numeric arguments to built-in
       macros shall be interpreted as decimal values. The string values
       produced as the defining text of the ddeeccrr, ddiivvnnuumm, iinnccrr, iinnddeexx, lleenn,
       and ssyyssvvaall built-in macros shall be in the form of a decimal-constant
       as defined in the C language.

       cchhaannggeeccoomm The cchhaannggeeccoomm 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.

       cchhaannggeeqquuoottee
                 The cchhaannggeeqquuoottee 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.

       ddeeccrr      The defining text of the ddeeccrr 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 ddeeccrr is not immediately followed by a
                 <left-parenthesis>.

       ddeeffiinnee    The second argument shall become the defining text of the
                 macro whose name is the first argument. It is unspecified
                 whether the ddeeffiinnee 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 ddeeffiinnee is not immediately followed by a <left-
                 parenthesis>.

       ddeeffnn      The defining text of the ddeeffnn macro shall be the quoted
                 definition (using the current quoting strings) of its
                 arguments. The behavior is unspecified if ddeeffnn is not
                 immediately followed by a <left-parenthesis>.

       ddiivveerrtt    The _m_4 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 ddiivveerrtt 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.

       ddiivvnnuumm    The defining text of the ddiivvnnuumm macro shall be the number of
                 the current output stream as a string.

       ddnnll       The ddnnll macro shall cause _m_4 to discard all input characters
                 up to and including the next <newline>.

       dduummppddeeff   The dduummppddeeff 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.

       eerrrrpprriinntt  The eerrrrpprriinntt macro shall write its arguments to standard
                 error. The behavior is unspecified if eerrrrpprriinntt is not
                 immediately followed by a <left-parenthesis>.

       eevvaall      The eevvaall 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 _S_e_c_t_i_o_n _1_._1_._2_._1, _A_r_i_t_h_m_e_t_i_c
                 _P_r_e_c_i_s_i_o_n _a_n_d _O_p_e_r_a_t_i_o_n_s:

                     (())
                     uunnaarryy ++
                     uunnaarryy --
                     ~~

                     !
                     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 eevvaall is not
                 immediately followed by a <left-parenthesis>.

       iiffddeeff     If the first argument to the iiffddeeff 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 iiffddeeff
                 is not immediately followed by a <left-parenthesis>.

       iiffeellssee    The iiffeellssee 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 iiffeellssee is not
                 immediately followed by a <left-parenthesis>.

       iinncclluuddee   The defining text for the iinncclluuddee 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
                 iinncclluuddee is not immediately followed by a <left-parenthesis>.

       iinnccrr      The defining text of the iinnccrr 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 iinnccrr is not immediately followed by a
                 <left-parenthesis>.

       iinnddeexx     The defining text of the iinnddeexx 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 iinnddeexx is not immediately followed by a <left-
                 parenthesis>.

       lleenn       The defining text of the lleenn macro shall be the length (as a
                 string) of the first argument.  The behavior is unspecified
                 if lleenn is not immediately followed by a <left-parenthesis>.

       mm44eexxiitt    Exit from the _m_4 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.

       mm44wwrraapp    The first argument shall be processed when EOF is reached. If
                 the mm44wwrraapp macro is used multiple times, the arguments
                 specified shall be processed in the order in which the mm44wwrraapp
                 macros were processed. The behavior is unspecified if mm44wwrraapp
                 is not immediately followed by a <left-parenthesis>.

       mmaakkeetteemmpp  The defining text shall be the first argument, with any
                 trailing ''XX'' characters replaced with the current process ID
                 as a string.  The behavior is unspecified if mmaakkeetteemmpp is not
                 immediately followed by a <left-parenthesis>.

       mmkksstteemmpp   The first argument shall be taken as a template for creating
                 an empty file, with trailing ''XX'' 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 ''XX'' 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 _u_m_a_s_k 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 mmkksstteemmpp is not
                 immediately followed by a <left-parenthesis>.

       ppooppddeeff    The ppooppddeeff 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 ppooppddeeff is not immediately
                 followed by a <left-parenthesis>.

       ppuusshhddeeff   The ppuusshhddeeff macro shall be equivalent to the ddeeffiinnee macro
                 with the exception that it shall preserve any current
                 definition for future retrieval using the ppooppddeeff macro. The
                 behavior is unspecified if ppuusshhddeeff is not immediately
                 followed by a <left-parenthesis>.

       sshhiifftt     The defining text for the sshhiifftt 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 sshhiifftt is not immediately
                 followed by a <left-parenthesis>.

       ssiinncclluuddee  The ssiinncclluuddee macro shall be equivalent to the iinncclluuddee macro,
                 except that it shall not be an error if the file is
                 inaccessible.  The behavior is unspecified if ssiinncclluuddee is not
                 immediately followed by a <left-parenthesis>.

       ssuubbssttrr    The defining text for the ssuubbssttrr 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 ssuubbssttrr is not immediately followed by a
                 <left-parenthesis>.

       ssyyssccmmdd    The ssyyssccmmdd 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 _m_4 utility. The
                 exit status value from the command can be retrieved using the
                 ssyyssvvaall macro. The behavior is unspecified if ssyyssccmmdd is not
                 immediately followed by a <left-parenthesis>.

       ssyyssvvaall    The defining text of the ssyyssvvaall macro shall be the exit value
                 of the utility last invoked by the ssyyssccmmdd macro (as a
                 string).

       ttrraacceeoonn   The ttrraacceeoonn 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.

       ttrraacceeooffff  The ttrraacceeooffff macro shall disable tracing for the macros
                 specified as arguments, or, if no arguments are specified,
                 for all macros.

       ttrraannsslliitt  The defining text of the ttrraannsslliitt 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 ttrraannsslliitt'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 ttrraannsslliitt is not immediately followed by a
                 <left-parenthesis>.

       uunnddeeffiinnee  The uunnddeeffiinnee macro shall delete all definitions (including
                 those preserved using the ppuusshhddeeff macro) of the macros named
                 by its arguments. The behavior is unspecified if uunnddeeffiinnee is
                 not immediately followed by a <left-parenthesis>.

       uunnddiivveerrtt  The uunnddiivveerrtt 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.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred

       If the mm44eexxiitt macro is used, the exit value can be specified by the
       input file.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The ddeeffnn macro is useful for renaming macros, especially built-ins.

       Since eevvaall 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 sshhiifftt
       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 ppuusshhddeeff macro, it is
       unspecified whether the ddeeffiinnee macro will alter only the most recent
       definition (as though by ppooppddeeff and ppuusshhddeeff), or replace the entire
       stack of definitions with a single definition (as though by uunnddeeffiinnee
       and ppuusshhddeeff).  An application desiring particular behavior for the
       ddeeffiinnee macro in this case can redefine it accordingly.

       Applications should use the mmkksstteemmpp macro instead of the obsolescent
       mmaakkeetteemmpp macro for creating temporary files.

EEXXAAMMPPLLEESS
       If the file mm44ssrrcc contains the lines:

           TThhee vvaalluuee ooff ``VVEERR'' iiss ""VVEERR""..
           iiffddeeff((``VVEERR'',, ````VVEERR'''' iiss ddeeffiinneedd ttoo bbee VVEERR..,, VVEERR iiss nnoott ddeeffiinneedd..))
           iiffeellssee((VVEERR,, 11,, ````VVEERR'''' iiss ``VVEERR''..))
           iiffeellssee((VVEERR,, 22,, ````VVEERR'''' iiss ``VVEERR''..,, ````VVEERR'''' iiss nnoott 22..))
           eenndd

       then the command

           mm44 mm44ssrrcc

       or the command:

           mm44 --UU VVEERR mm44ssrrcc

       produces the output:

           TThhee vvaalluuee ooff VVEERR iiss ""VVEERR""..
           VVEERR iiss nnoott ddeeffiinneedd..

           VER is not 2.
           end

       The command:

           mm44 --DD VVEERR mm44ssrrcc

       produces the output:

           TThhee vvaalluuee ooff VVEERR iiss """"..
           VVEERR iiss ddeeffiinneedd ttoo bbee ..

           VER is not 2.
           end

       The command:

           mm44 --DD VVEERR==11 mm44ssrrcc

       produces the output:

           TThhee vvaalluuee ooff VVEERR iiss ""11""..
           VVEERR iiss ddeeffiinneedd ttoo bbee 11..
           VVEERR iiss 11..
           VVEERR iiss nnoott 22..
           eenndd

       The command:

           mm44 --DD VVEERR==22 mm44ssrrcc

       produces the output:

           TThhee vvaalluuee ooff VVEERR iiss ""22""..
           VVEERR iiss ddeeffiinneedd ttoo bbee 22..

           VER is 2.
           end

RRAATTIIOONNAALLEE
       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 ""$${{1111}}"" 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 ttrraannsslliitt 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_9_9

       The Base Definitions volume of POSIX.1-2008, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       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(1)
