1M4(1P) POSIX Programmer's Manual M4(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 m4 — macro processor
13
15 m4 [-s] [-D name[=val]]... [-U name]... file...
16
18 The m4 utility is a macro processor that shall read one or more text
19 files, process them according to their included macro statements, and
20 write the results to standard output.
21
23 The m4 utility shall conform to the Base Definitions volume of
24 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines, except that the
25 order of the -D and -U options shall be significant, and options can be
26 interspersed with operands.
27 The following options shall be supported:
29 -s Enable line synchronization output for the c99 preprocessor
31 phase (that is, #line directives).
32 -D name[=val]
34 Define name to val or to null if =val is omitted.
35 -U name Undefine name.
37
39 The following operand shall be supported:
40 file A pathname of a text file to be processed. If no file is
42 given, or if it is '-', the standard input shall be read.
43
45 The standard input shall be a text file that is used if no file operand
46 is given, or if it is '-'.
47
49 The input file named by the file operand shall be a text file.
50
52 The following environment variables shall affect the execution of m4:
53 LANG Provide a default value for the internationalization vari‐
55 ables that are unset or null. (See the Base Definitions vol‐
56 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
57 ables for the precedence of internationalization variables
58 used to determine the values of locale categories.)
59 LC_ALL If set to a non-empty string value, override the values of
61 all the other internationalization variables.
62 LC_CTYPE Determine the locale for the interpretation of sequences of
64 bytes of text data as characters (for example, single-byte as
65 opposed to multi-byte characters in arguments and input
66 files).
67 LC_MESSAGES
69 Determine the locale that should be used to affect the format
70 and contents of diagnostic messages written to standard
71 error.
72 NLSPATH Determine the location of message catalogs for the processing
74 of LC_MESSAGES.
75
77 Default.
78
80 The standard output shall be the same as the input files, after being
81 processed for macro expansion.
82
84 The standard error shall be used to display strings with the errprint
85 macro, macro tracing enabled by the traceon macro, the defined text for
86 macros written by the dumpdef macro, or for diagnostic messages.
87
89 None.
90
92 The m4 utility shall compare each token from the input against the set
93 of built-in and user-defined macros. If the token matches the name of a
94 macro, then the token shall be replaced by the macro's defining text,
95 if any, and rescanned for matching macro names. Once no portion of the
96 token matches the name of a macro, it shall be written to standard out‐
97 put. Macros may have arguments, in which case the arguments shall be
98 substituted into the defining text before it is rescanned.
99 Macro calls have the form:
101 name(arg1, arg2, ..., argn)
104 Macro names shall consist of letters, digits, and underscores, where
106 the first character is not a digit. Tokens not of this form shall not
107 be treated as macros.
108 The application shall ensure that the <left-parenthesis> immediately
110 follows the name of the macro. If a token matching the name of a macro
111 is not followed by a <left-parenthesis>, it is handled as a use of that
112 macro without arguments.
113 If a macro name is followed by a <left-parenthesis>, its arguments are
115 the <comma>-separated tokens between the <left-parenthesis> and the
116 matching <right-parenthesis>. Unquoted white-space characters preced‐
117 ing each argument shall be ignored. All other characters, including
118 trailing white-space characters, are retained. <comma> characters
119 enclosed between <left-parenthesis> and <right-parenthesis> characters
120 do not delimit arguments.
121 Arguments are positionally defined and referenced. The string "$1" in
123 the defining text shall be replaced by the first argument. Systems
124 shall support at least nine arguments; only the first nine can be ref‐
125 erenced, using the strings "$1" to "$9", inclusive. The string "$0" is
126 replaced with the name of the macro. The string "$#" is replaced by the
127 number of arguments as a string. The string "$*" is replaced by a list
128 of all of the arguments, separated by <comma> characters. The string
129 "$@" is replaced by a list of all of the arguments separated by <comma>
130 characters, and each argument is quoted using the current left and
131 right quoting strings. The string "${" produces unspecified behavior.
132 If fewer arguments are supplied than are in the macro definition, the
134 omitted arguments are taken to be null. It is not an error if more
135 arguments are supplied than are in the macro definition.
136 No special meaning is given to any characters enclosed between matching
138 left and right quoting strings, but the quoting strings are themselves
139 discarded. By default, the left quoting string consists of a grave
140 accent (backquote) and the right quoting string consists of an acute
141 accent (single-quote); see also the changequote macro.
142 Comments are written but not scanned for matching macro names; by
144 default, the begin-comment string consists of the <number-sign> charac‐
145 ter and the end-comment string consists of a <newline>. See also the
146 changecom and dnl macros.
147 The m4 utility shall make available the following built-in macros. They
149 can be redefined, but once this is done the original meaning is lost.
150 Their values shall be null unless otherwise stated. In the descriptions
151 below, the term defining text refers to the value of the macro: the
152 second argument to the define macro, among other things. Except for the
153 first argument to the eval macro, all numeric arguments to built-in
154 macros shall be interpreted as decimal values. The string values pro‐
155 duced as the defining text of the decr, divnum, incr, index, len, and
156 sysval built-in macros shall be in the form of a decimal-constant as
157 defined in the C language.
158 changecom The changecom macro shall set the begin-comment and end-com‐
160 ment strings. With no arguments, the comment mechanism shall
161 be disabled. With a single non-null argument, that argument
162 shall become the begin-comment and the <newline> shall become
163 the end-comment string. With two non-null arguments, the
164 first argument shall become the begin-comment string and the
165 second argument shall become the end-comment string. The
166 behavior is unspecified if either argument is provided but
167 null. Systems shall support comment strings of at least five
168 characters.
169 changequote
171 The changequote macro shall set the begin-quote and end-quote
172 strings. With no arguments, the quote strings shall be set to
173 the default values (that is, `'). The behavior is unspecified
174 if there is a single argument or either argument is null.
175 With two non-null arguments, the first argument shall become
176 the begin-quote string and the second argument shall become
177 the end-quote string. Systems shall support quote strings of
178 at least five characters.
179 decr The defining text of the decr macro shall be its first argu‐
181 ment decremented by 1. It shall be an error to specify an
182 argument containing any non-numeric characters. The behavior
183 is unspecified if decr is not immediately followed by a
184 <left-parenthesis>.
185 define The second argument shall become the defining text of the
187 macro whose name is the first argument. It is unspecified
188 whether the define macro deletes all prior definitions of the
189 macro named by its first argument or preserves all but the
190 current definition of the macro. The behavior is unspecified
191 if define is not immediately followed by a <left-parenthe‐
192 sis>.
193 defn The defining text of the defn macro shall be the quoted defi‐
195 nition (using the current quoting strings) of its arguments.
196 The behavior is unspecified if defn is not immediately fol‐
197 lowed by a <left-parenthesis>.
198 divert The m4 utility maintains nine temporary buffers, numbered 1
200 to 9, inclusive. When the last of the input has been pro‐
201 cessed, any output that has been placed in these buffers
202 shall be written to standard output in buffer-numerical
203 order. The divert macro shall divert future output to the
204 buffer specified by its argument. Specifying no argument or
205 an argument of 0 shall resume the normal output process. Out‐
206 put diverted to a stream with a negative number shall be dis‐
207 carded. Behavior is implementation-defined if a stream number
208 larger than 9 is specified. It shall be an error to specify
209 an argument containing any non-numeric characters.
210 divnum The defining text of the divnum macro shall be the number of
212 the current output stream as a string.
213 dnl The dnl macro shall cause m4 to discard all input characters
215 up to and including the next <newline>.
216 dumpdef The dumpdef macro shall write the defined text to standard
218 error for each of the macros specified as arguments, or, if
219 no arguments are specified, for all macros.
220 errprint The errprint macro shall write its arguments to standard
222 error. The behavior is unspecified if errprint is not immedi‐
223 ately followed by a <left-parenthesis>.
224 eval The eval macro shall evaluate its first argument as an arith‐
226 metic expression, using signed integer arithmetic with at
227 least 32-bit precision. At least the following C-language
228 operators shall be supported, with precedence, associativity,
229 and behavior as described in Section 1.1.2.1, Arithmetic Pre‐
230 cision and Operations:
231 ()
234 unary +
235 unary -
236 ~
237 !
239 binary *
240 /
241 %
242 binary +
243 binary -
244 <<
245 >>
246 <
247 <=
248 >
249 >=
250 ==
251 !=
252 binary &
253 ^
254 |
255 &&
256 ||
257 Systems shall support octal and hexadecimal numbers as in the
259 ISO C standard. The second argument, if specified, shall set
260 the radix for the result; if the argument is blank or unspec‐
261 ified, the default is 10. Behavior is unspecified if the
262 radix falls outside the range 2 to 36, inclusive. The third
263 argument, if specified, sets the minimum number of digits in
264 the result. Behavior is unspecified if the third argument is
265 less than zero. It shall be an error to specify the second or
266 third argument containing any non-numeric characters. The
267 behavior is unspecified if eval is not immediately followed
268 by a <left-parenthesis>.
269 ifdef If the first argument to the ifdef macro is defined, the
271 defining text shall be the second argument. Otherwise, the
272 defining text shall be the third argument, if specified, or
273 the null string, if not. The behavior is unspecified if ifdef
274 is not immediately followed by a <left-parenthesis>.
275 ifelse The ifelse macro takes three or more arguments. If the first
277 two arguments compare as equal strings (after macro expansion
278 of both arguments), the defining text shall be the third
279 argument. If the first two arguments do not compare as equal
280 strings and there are three arguments, the defining text
281 shall be null. If the first two arguments do not compare as
282 equal strings and there are four or five arguments, the
283 defining text shall be the fourth argument. If the first two
284 arguments do not compare as equal strings and there are six
285 or more arguments, the first three arguments shall be dis‐
286 carded and processing shall restart with the remaining argu‐
287 ments. The behavior is unspecified if ifelse is not immedi‐
288 ately followed by a <left-parenthesis>.
289 include The defining text for the include macro shall be the contents
291 of the file named by the first argument. It shall be an error
292 if the file cannot be read. The behavior is unspecified if
293 include is not immediately followed by a <left-parenthesis>.
294 incr The defining text of the incr macro shall be its first argu‐
296 ment incremented by 1. It shall be an error to specify an
297 argument containing any non-numeric characters. The behavior
298 is unspecified if incr is not immediately followed by a
299 <left-parenthesis>.
300 index The defining text of the index macro shall be the first char‐
302 acter position (as a string) in the first argument where a
303 string matching the second argument begins (zero origin), or
304 -1 if the second argument does not occur. The behavior is
305 unspecified if index is not immediately followed by a <left-
306 parenthesis>.
307 len The defining text of the len macro shall be the length (as a
309 string) of the first argument. The behavior is unspecified
310 if len is not immediately followed by a <left-parenthesis>.
311 m4exit Exit from the m4 utility. If the first argument is specified,
313 it shall be the exit code. If no argument is specified, the
314 exit code shall be zero. It shall be an error to specify an
315 argument containing any non-numeric characters. If the first
316 argument is zero or no argument is specified, and an error
317 has previously occurred (for example, a file operand that
318 could not be opened), it is unspecified whether the exit sta‐
319 tus is zero or non-zero.
320 m4wrap The first argument shall be processed when EOF is reached. If
322 the m4wrap macro is used multiple times, the arguments speci‐
323 fied shall be processed in the order in which the m4wrap
324 macros were processed. The behavior is unspecified if m4wrap
325 is not immediately followed by a <left-parenthesis>.
326 maketemp The defining text shall be the first argument, with any
328 trailing 'X' characters replaced with the current process ID
329 as a string. The behavior is unspecified if maketemp is not
330 immediately followed by a <left-parenthesis>.
331 mkstemp The defining text shall be as if it were the resulting path‐
333 name after a successful call to the mkstemp() function
334 defined in the System Interfaces volume of POSIX.1‐2017
335 called with the first argument to the macro invocation. If a
336 file is created, that file shall be closed. If a file could
337 not be created, the m4 utility shall write a diagnostic mes‐
338 sage to standard error and shall continue processing input
339 but its final exit status shall be non-zero; the defining
340 text of the macro shall be the empty string. The behavior is
341 unspecified if mkstemp is not immediately followed by a
342 <left-parenthesis>.
343 popdef The popdef macro shall delete the current definition of its
345 arguments, replacing that definition with the previous one.
346 If there is no previous definition, the macro is undefined.
347 The behavior is unspecified if popdef is not immediately fol‐
348 lowed by a <left-parenthesis>.
349 pushdef The pushdef macro shall be equivalent to the define macro
351 with the exception that it shall preserve any current defini‐
352 tion for future retrieval using the popdef macro. The behav‐
353 ior is unspecified if pushdef is not immediately followed by
354 a <left-parenthesis>.
355 shift The defining text for the shift macro shall be a comma-sepa‐
357 rated list of its arguments except the first one. Each argu‐
358 ment shall be quoted using the current quoting strings. The
359 behavior is unspecified if shift is not immediately followed
360 by a <left-parenthesis>.
361 sinclude The sinclude macro shall be equivalent to the include macro,
363 except that it shall not be an error if the file is inacces‐
364 sible. The behavior is unspecified if sinclude is not imme‐
365 diately followed by a <left-parenthesis>.
366 substr The defining text for the substr macro shall be the substring
368 of the first argument beginning at the zero-offset character
369 position specified by the second argument. The third argu‐
370 ment, if specified, shall be the number of characters to
371 select; if not specified, the characters from the starting
372 point to the end of the first argument shall become the
373 defining text. It shall not be an error to specify a starting
374 point beyond the end of the first argument and the defining
375 text shall be null. It shall be an error to specify an argu‐
376 ment containing any non-numeric characters. The behavior is
377 unspecified if substr is not immediately followed by a <left-
378 parenthesis>.
379 syscmd The syscmd macro shall interpret its first argument as a
381 shell command line. The defining text shall be the string
382 result of that command. The string result shall not be res‐
383 canned for macros while setting the defining text. No output
384 redirection shall be performed by the m4 utility. The exit
385 status value from the command can be retrieved using the sys‐
386 val macro. The behavior is unspecified if syscmd is not imme‐
387 diately followed by a <left-parenthesis>.
388 sysval The defining text of the sysval macro shall be the exit value
390 of the utility last invoked by the syscmd macro (as a
391 string).
392 traceon The traceon macro shall enable tracing for the macros speci‐
394 fied as arguments, or, if no arguments are specified, for all
395 macros. The trace output shall be written to standard error
396 in an unspecified format.
397 traceoff The traceoff macro shall disable tracing for the macros spec‐
399 ified as arguments, or, if no arguments are specified, for
400 all macros.
401 translit The defining text of the translit macro shall be the first
403 argument with every character that occurs in the second argu‐
404 ment replaced with the corresponding character from the third
405 argument. If no replacement character is specified for some
406 source character because the second argument is longer than
407 the third argument, that character shall be deleted from the
408 first argument in translit's defining text. The behavior is
409 unspecified if the '-' character appears within the second or
410 third argument anywhere besides the first or last character.
411 The behavior is unspecified if the same character appears
412 more than once in the second argument. The behavior is
413 unspecified if translit is not immediately followed by a
414 <left-parenthesis>.
415 undefine The undefine macro shall delete all definitions (including
417 those preserved using the pushdef macro) of the macros named
418 by its arguments. The behavior is unspecified if undefine is
419 not immediately followed by a <left-parenthesis>.
420 undivert The undivert macro shall cause immediate output of any text
422 in temporary buffers named as arguments, or all temporary
423 buffers if no arguments are specified. Buffers can be undi‐
424 verted into other temporary buffers. Undiverting shall dis‐
425 card the contents of the temporary buffer. The behavior is
426 unspecified if an argument contains any non-numeric charac‐
427 ters.
428
430 The following exit values shall be returned:
431 0 Successful completion.
433 >0 An error occurred
435 If the m4exit macro is used, the exit value can be specified by the
437 input file.
438
440 Default.
441 The following sections are informative.
443
445 The defn macro is useful for renaming macros, especially built-ins.
446 Since eval defers to the ISO C standard, some operations have undefined
448 behavior. In some implementations, division or remainder by zero cause
449 a fatal signal, even if the division occurs on the short-circuited
450 branch of "&&" or "||". Any operation that overflows in signed arith‐
451 metic produces undefined behavior. Likewise, using the shift operators
452 with a shift amount that is not positive and smaller than the precision
453 is undefined, as is shifting a negative number to the right. Histori‐
454 cally, not all implementations obeyed C-language precedence rules: '~'
455 and '!' were lower than '=='; '==' and '!=' were not lower than '<';
456 and '|' was not lower than '^'; the liberal use of "()" can force the
457 desired precedence even with these non-compliant implementations. Fur‐
458 thermore, some traditional implementations treated '^' as an exponenti‐
459 ation operator, although most implementations now use "**" as an exten‐
460 sion for this purpose.
461 When a macro has been multiply defined via the pushdef macro, it is
463 unspecified whether the define macro will alter only the most recent
464 definition (as though by popdef and pushdef), or replace the entire
465 stack of definitions with a single definition (as though by undefine
466 and pushdef). An application desiring particular behavior for the
467 define macro in this case can redefine it accordingly.
468 Applications should use the mkstemp macro instead of the obsolescent
470 maketemp macro for creating temporary files.
471
473 If the file m4src contains the lines:
474 The value of `VER' is "VER".
477 ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
478 ifelse(VER, 1, ``VER'' is `VER'.)
479 ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
480 end
481 then the command
483 m4 m4src
486 or the command:
488 m4 -U VER m4src
491 produces the output:
493 The value of VER is "VER".
496 VER is not defined.
497 VER is not 2.
499 end
500 The command:
502 m4 -D VER m4src
505 produces the output:
507 The value of VER is "".
510 VER is defined to be .
511 VER is not 2.
513 end
514 The command:
516 m4 -D VER=1 m4src
519 produces the output:
521 The value of VER is "1".
524 VER is defined to be 1.
525 VER is 1.
526 VER is not 2.
527 end
528 The command:
530 m4 -D VER=2 m4src
533 produces the output:
535 The value of VER is "2".
538 VER is defined to be 2.
539 VER is 2.
541 end
542
544 Historic System V-based behavior treated "${" in a macro definition as
545 two literal characters. However, this sequence is left unspecified so
546 that implementations may offer extensions such as "${11}" meaning the
547 eleventh positional parameter. Macros can still be defined with appro‐
548 priate uses of nested quoting to result in a literal "${" in the output
549 after rescanning removes the nested quotes.
550 In the translit built-in, historic System V-based behavior treated '-'
552 as a literal; GNU behavior treats it as a range. This version of the
553 standard allows either behavior.
554
556 None.
557
559 c99
560 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
562 Variables, Section 12.2, Utility Syntax Guidelines
563
565 Portions of this text are reprinted and reproduced in electronic form
566 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
567 table Operating System Interface (POSIX), The Open Group Base Specifi‐
568 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
569 Electrical and Electronics Engineers, Inc and The Open Group. In the
570 event of any discrepancy between this version and the original IEEE and
571 The Open Group Standard, the original IEEE and The Open Group Standard
572 is the referee document. The original Standard can be obtained online
573 at http://www.opengroup.org/unix/online.html .
574 Any typographical or formatting errors that appear in this page are
576 most likely to have been introduced during the conversion of the source
577 files to man page format. To report such errors, see https://www.ker‐
578 nel.org/doc/man-pages/reporting_bugs.html .
579IEEE/The Open Group 2017 M4(1P)