M4(1POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 M4(1POSIX) 💖 — macro processor, bestie edition

okay so this is the POSIX Programmer's Manual, section 1POSIX, and today we're doing m4. She's a macro processor. She's been running build systems since before you were born. Respect her. 👑

🌸 PROLOG 🌸

This manual page is part of the POSIX Programmer's Manual. That said, the Linux implementation of this interface may differ — so like, consult the corresponding Linux manual page for details on Linux behavior — or honestly the interface may not be implemented on Linux at all. Vibe check accordingly, bestie. 🙈

✨ NAME ✨

m4 — macro processor. That's the whole job. No notes. 💅

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

The m4 utility is a macro processor. It shall read one or more text files, process them according to their included macro statements, and write the results to standard output. It's giving "text goes in, expanded text comes out, you cannot explain that." ✨

💅 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. Yes, the ORDER MATTERS. This is not a drill. Read it twice. 🫶

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. (Yes, - means "read my stdin." Classic. Iconic. Never changes.)

🌈 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. That's it. She said "no thoughts, head empty," and honestly? Same. 💀

🔥 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 🌸

okay so THIS is the main character section, pull up a chair and a snack 🫶🍓

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. (So like, _girlboss1 is a valid macro name. 1girlboss is not. Rules are rules. 💅)

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.

bestie. NOT the "${". That one's giving ✨unspecified behavior✨ and we do not trust her. 🙈

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. (Generous queen. She's not gonna yell at you about it. 💖)

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.

🎁 THE BUILT-INS 🎁

  • 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 -
~

okay and we're literally not even done, bestie — the operator list keeps going and so do we. next part incoming, don't go anywhere 💖

so eval is out here doing math and it supports these operators, periodt:

  • !
  • binary *
  • /
  • %
  • binary +
  • binary -
  • <<
  • >>
  • <
  • <=
  • >
  • >=
  • ==
  • !=
  • binary &
  • ^
  • |
  • &&
  • ||

systems gotta support octal and hex numbers as in the ISO C standard, no cap. the second arg, if you give one, sets the radix for the result; if it's blank or unspecified, the default is 10. behavior is unspecified if the radix falls outside the range 2 to 36, inclusive. the third arg, if specified, sets the minimum number of digits in the result. behavior is unspecified if the third arg is less than zero. it's literally an error to specify a second or third arg containing any non-numeric characters. and behavior is unspecified if eval isn't immediately followed by a <left-parenthesis>. 💅

ifdef

if the first arg to ifdef is defined, the defining text is the second arg. otherwise, the defining text is the third arg, if specified, or the null string, if not. behavior is unspecified if ifdef isn't immediately followed by a <left-parenthesis>. 🎀

ifelse

ifelse takes three or more arguments. if the first two args compare as equal strings (after macro expansion of both args), the defining text is the third arg. if the first two args do not compare as equal strings and there are three args, the defining text is null. if the first two args do not compare as equal strings and there are four or five args, the defining text is the fourth arg. if the first two args do not compare as equal strings and there are six or more args, the first three args are discarded and processing restarts with the remaining args. behavior is unspecified if ifelse isn't immediately followed by a <left-parenthesis>. 🦋

include

the defining text for include is the contents of the file named by the first arg. it's an error if the file can't be read. behavior is unspecified if include isn't immediately followed by a <left-parenthesis>. 📂

incr

the defining text of incr is its first arg incremented by 1. it's an error to specify an arg containing any non-numeric characters. behavior is unspecified if incr isn't immediately followed by a <left-parenthesis>. 🔢

index

the defining text of index is the first character position (as a string) in the first arg where a string matching the second arg begins (zero origin), or -1 if the second arg doesn't occur. behavior is unspecified if index isn't immediately followed by a <left-parenthesis>. 🔍

len

the defining text of len is the length (as a string) of the first arg. behavior is unspecified if len isn't immediately followed by a <left-parenthesis>. 📏

m4exit

m4exit exits from the m4 utility. if the first arg is specified, it's the exit code. if no arg is specified, the exit code is 0. it's an error to specify an arg containing any non-numeric characters. if the first arg is zero or no arg is specified, and an error has previously occurred (for example, a file operand that couldn't be opened), it's unspecified whether the exit status is zero or non-zero. 🚪

m4wrap

the first arg gets processed when EOF is reached. if you use m4wrap multiple times, the args specified are processed in the order in which the m4wrap macros were processed. behavior is unspecified if m4wrap isn't immediately followed by a <left-parenthesis>. 🎁

maketemp

the defining text is the first arg, with any trailing 'X' characters replaced with the current process ID as a string. behavior is unspecified if maketemp isn't immediately followed by a <left-parenthesis>. 🆔

mkstemp

the defining text is 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 arg to the macro invocation. if a file is created, that file gets closed. if a file couldn't be created, the m4 utility writes a diagnostic message to standard error and continues processing input but its final exit status is non-zero; the defining text of the macro is the empty string. behavior is unspecified if mkstemp isn't immediately followed by a <left-parenthesis>. 📁

popdef

popdef deletes the current definition of its args, replacing that definition with the previous one. if there's no previous definition, the macro is undefined. behavior is unspecified if popdef isn't immediately followed by a <left-parenthesis>. 🗑️

pushdef

pushdef is equivalent to the define macro except it preserves any current definition for future retrieval using the popdef macro. behavior is unspecified if pushdef isn't immediately followed by a <left-parenthesis>. 📌

shift

the defining text for shift is a comma-separated list of its args except the first one. each arg is quoted using the current quoting strings. behavior is unspecified if shift isn't immediately followed by a <left-parenthesis>. 👋

sinclude

sinclude is equivalent to the include macro, except it's not an error if the file is inaccessible. behavior is unspecified if sinclude isn't immediately followed by a <left-parenthesis>. 🕊️

substr

the defining text for substr is the substring of the first arg beginning at the zero-offset character position specified by the second arg. the third arg, if specified, is the number of characters to select; if not specified, the characters from the starting point to the end of the first arg become the defining text. it's not an error to specify a starting point beyond the end of the first arg and the defining text is null. it's an error to specify an arg containing any non-numeric characters. behavior is unspecified if substr isn't immediately followed by a <left-parenthesis>. ✂️

syscmd

syscmd interprets its first arg as a shell command line. the defining text is the string result of that command. that string result is not rescanned for macros while setting the defining text. no output redirection is performed by the m4 utility. the exit status value from the command can be retrieved using the sysval macro. behavior is unspecified if syscmd isn't immediately followed by a <left-parenthesis>. 💻

sysval

the defining text of sysval is the exit value of the utility last invoked by the syscmd macro (as a string). 📊

traceon

traceon enables tracing for the macros specified as args, or, if no args are specified, for all macros. the trace output is written to standard error in an unspecified format. 🔎

traceoff

traceoff disables tracing for the macros specified as args, or, if no args are specified, for all macros. 🔇

translit

the defining text of translit is the first arg with every character that occurs in the second arg replaced with the corresponding character from the third arg. if no replacement character is specified for some source character because the second arg is longer than the third arg, that character is deleted from the first arg in translit's defining text. behavior is unspecified if the '-' character appears within the second or third arg anywhere besides the first or last character. behavior is unspecified if the same character appears more than once in the second arg. behavior is unspecified if translit isn't immediately followed by a <left-parenthesis>. 🔄

undefine

undefine deletes all definitions (including those preserved using the pushdef macro) of the macros named by its args. behavior is unspecified if undefine isn't immediately followed by a <left-parenthesis>. 💥

undivert

undivert causes immediate output of any text in temporary buffers named as args, or all temporary buffers if no args are specified. buffers can be undiverted into other temporary buffers. undiverting discards the contents of the temporary buffer. behavior is unspecified if an arg 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 🎀

So the defn macro? Absolute baddie for renaming macros, especially the built-in ones. Like, renaming built-ins is literally its whole moment. 💅

And bestie, listen — because eval defers to the ISO C standard, some operations have undefined behavior. Not being dramatic, this is real:

  • In some implementations, division or remainder by zero cause a fatal signal — and yes, even if that division is sitting on the short-circuited branch of && or ||. Rude, but true. 💀
  • Any operation that overflows in signed arithmetic produces undefined behavior.
  • Using the shift operators with a shift amount that is not positive and smaller than the precision is undefined. Same energy for 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 precedence you actually want even with these non-compliant implementations. Lowkey a lifesaver. 🫶
  • Also, some traditional implementations treated ^ as an exponentiation operator, even though most implementations now use ** as an extension for that purpose.

Now, when a macro has been multiply defined via the pushdef macro, it is unspecified whether the define macro will:

  1. alter only the most recent definition (as though by popdef and pushdef), or
  2. replace the entire stack of definitions with a single definition (as though by undefine and pushdef).

An application that wants a specific behavior for define in this situation can just redefine it accordingly. Main character move, honestly. ✨

Also: applications should use the mkstemp macro instead of the obsolescent maketemp macro for creating temporary files. mkstemp ate, maketemp is giving retired. 👑

✨ EXAMPLES ✨

Okay so if the file m4src contains these 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

Look at her go. 🌈 Every single one of those is a whole vibe check on how VER gets defined. Obsessed.

💭 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. And don't worry — 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. Nested quoting really said "I got you." 🧚

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. Both are valid, it's giving choose-your-own-adventure. 🦋

🔮 FUTURE DIRECTIONS 🔮

None. Not a single one. The future is a blank canvas, bestie. 💜

🌸 SEE ALSO 🌸

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

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

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 .

and that's the whole page, bestie 💖 go forth and macro responsibly ✨

This one came from IEEE/The Open Group, dated 2017, and it's M4(1POSIX). That's a wrap, ily, drink water, pushdef before you define 🎀🫶💅

📦 where this page comes from