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
13 m4 — macro processor
14
16 m4 [−s] [−D name[=val]]... [−U name]... file...
17
19 The m4 utility is a macro processor that shall read one or more text
20 files, process them according to their included macro statements, and
21 write the results to standard output.
22
24 The m4 utility shall conform to the Base Definitions volume of
25 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines, except that the
26 order of the −D and −U options shall be significant, and options can be
27 interspersed with operands.
28 The following options shall be supported:
30 −s Enable line synchronization output for the c99 preprocessor
32 phase (that is, #line directives).
33 −D name[=val]
35 Define name to val or to null if =val is omitted.
36 −U name Undefine name.
38
40 The following operand shall be supported:
41 file A pathname of a text file to be processed. If no file is
43 given, or if it is '−', the standard input shall be read.
44
46 The standard input shall be a text file that is used if no file operand
47 is given, or if it is '−'.
48
50 The input file named by the file operand shall be a text file.
51
53 The following environment variables shall affect the execution of m4:
54 LANG Provide a default value for the internationalization vari‐
56 ables that are unset or null. (See the Base Definitions vol‐
57 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
58 ables for the precedence of internationalization variables
59 used to determine the values of locale categories.)
60 LC_ALL If set to a non-empty string value, override the values of
62 all the other internationalization variables.
63 LC_CTYPE Determine the locale for the interpretation of sequences of
65 bytes of text data as characters (for example, single-byte as
66 opposed to multi-byte characters in arguments and input
67 files).
68 LC_MESSAGES
70 Determine the locale that should be used to affect the format
71 and contents of diagnostic messages written to standard
72 error.
73 NLSPATH Determine the location of message catalogs for the processing
75 of LC_MESSAGES.
76
78 Default.
79
81 The standard output shall be the same as the input files, after being
82 processed for macro expansion.
83
85 The standard error shall be used to display strings with the errprint
86 macro, macro tracing enabled by the traceon macro, the defined text for
87 macros written by the dumpdef macro, or for diagnostic messages.
88
90 None.
91
93 The m4 utility shall compare each token from the input against the set
94 of built-in and user-defined macros. If the token matches the name of a
95 macro, then the token shall be replaced by the macro's defining text,
96 if any, and rescanned for matching macro names. Once no portion of the
97 token matches the name of a macro, it shall be written to standard out‐
98 put. Macros may have arguments, in which case the arguments shall be
99 substituted into the defining text before it is rescanned.
100 Macro calls have the form:
102 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 ()
233 unary +
234 unary −
235 ~
236 !
238 binary *
239 /
240 %
241 binary +
242 binary −
243 <<
244 >>
245 <
246 <=
247 >
248 >=
249 ==
250 !=
251 binary &
252 ^
253 |
254 &&
255 ||
256 Systems shall support octal and hexadecimal numbers as in the
258 ISO C standard. The second argument, if specified, shall set
259 the radix for the result; if the argument is blank or unspec‐
260 ified, the default is 10. Behavior is unspecified if the
261 radix falls outside the range 2 to 36, inclusive. The third
262 argument, if specified, sets the minimum number of digits in
263 the result. Behavior is unspecified if the third argument is
264 less than zero. It shall be an error to specify the second or
265 third argument containing any non-numeric characters. The
266 behavior is unspecified if eval is not immediately followed
267 by a <left-parenthesis>.
268 ifdef If the first argument to the ifdef macro is defined, the
270 defining text shall be the second argument. Otherwise, the
271 defining text shall be the third argument, if specified, or
272 the null string, if not. The behavior is unspecified if ifdef
273 is not immediately followed by a <left-parenthesis>.
274 ifelse The ifelse macro takes three or more arguments. If the first
276 two arguments compare as equal strings (after macro expansion
277 of both arguments), the defining text shall be the third
278 argument. If the first two arguments do not compare as equal
279 strings and there are three arguments, the defining text
280 shall be null. If the first two arguments do not compare as
281 equal strings and there are four or five arguments, the
282 defining text shall be the fourth argument. If the first two
283 arguments do not compare as equal strings and there are six
284 or more arguments, the first three arguments shall be dis‐
285 carded and processing shall restart with the remaining argu‐
286 ments. The behavior is unspecified if ifelse is not immedi‐
287 ately followed by a <left-parenthesis>.
288 include The defining text for the include macro shall be the contents
290 of the file named by the first argument. It shall be an error
291 if the file cannot be read. The behavior is unspecified if
292 include is not immediately followed by a <left-parenthesis>.
293 incr The defining text of the incr macro shall be its first argu‐
295 ment incremented by 1. It shall be an error to specify an
296 argument containing any non-numeric characters. The behavior
297 is unspecified if incr is not immediately followed by a
298 <left-parenthesis>.
299 index The defining text of the index macro shall be the first char‐
301 acter position (as a string) in the first argument where a
302 string matching the second argument begins (zero origin), or
303 −1 if the second argument does not occur. The behavior is
304 unspecified if index is not immediately followed by a <left-
305 parenthesis>.
306 len The defining text of the len macro shall be the length (as a
308 string) of the first argument. The behavior is unspecified
309 if len is not immediately followed by a <left-parenthesis>.
310 m4exit Exit from the m4 utility. If the first argument is specified,
312 it is the exit code. The default is zero. It shall be an
313 error to specify an argument containing any non-numeric char‐
314 acters.
315 m4wrap The first argument shall be processed when EOF is reached. If
317 the m4wrap macro is used multiple times, the arguments speci‐
318 fied shall be processed in the order in which the m4wrap
319 macros were processed. The behavior is unspecified if m4wrap
320 is not immediately followed by a <left-parenthesis>.
321 maketemp The defining text shall be the first argument, with any
323 trailing 'X' characters replaced with the current process ID
324 as a string. The behavior is unspecified if maketemp is not
325 immediately followed by a <left-parenthesis>.
326 mkstemp The first argument shall be taken as a template for creating
328 an empty file, with trailing 'X' characters replaced with
329 characters from the portable filename character set. The
330 behavior is unspecified if the first argument does not end in
331 at least six 'X' characters. If a temporary file is success‐
332 fully created, then the defining text of the macro shall be
333 the name of the new file. The user ID of the file shall be
334 set to the effective user ID of the process. The group ID of
335 the file shall be set to the group ID of the file's parent
336 directory or to the effective group ID of the process. The
337 file access permission bits are set such that only the owner
338 can both read and write the file, regardless of the current
339 umask of the process. If a file could not be created, the
340 defining text of the macro shall be the empty string. The
341 behavior is unspecified if mkstemp is not immediately fol‐
342 lowed by a <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".
476 ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
477 ifelse(VER, 1, ``VER'' is `VER'.)
478 ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
479 end
480 then the command
482 m4 m4src
484 or the command:
486 m4 −U VER m4src
488 produces the output:
490 The value of VER is "VER".
492 VER is not defined.
493 VER is not 2.
495 end
496 The command:
498 m4 −D VER m4src
500 produces the output:
502 The value of VER is "".
504 VER is defined to be .
505 VER is not 2.
507 end
508 The command:
510 m4 −D VER=1 m4src
512 produces the output:
514 The value of VER is "1".
516 VER is defined to be 1.
517 VER is 1.
518 VER is not 2.
519 end
520 The command:
522 m4 −D VER=2 m4src
524 produces the output:
526 The value of VER is "2".
528 VER is defined to be 2.
529 VER is 2.
531 end
532
534 Historic System V-based behavior treated "${" in a macro definition as
535 two literal characters. However, this sequence is left unspecified so
536 that implementations may offer extensions such as "${11}" meaning the
537 eleventh positional parameter. Macros can still be defined with appro‐
538 priate uses of nested quoting to result in a literal "${" in the output
539 after rescanning removes the nested quotes.
540 In the translit built-in, historic System V-based behavior treated '−'
542 as a literal; GNU behavior treats it as a range. This version of the
543 standard allows either behavior.
544
546 None.
547
549 c99
550 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
552 Variables, Section 12.2, Utility Syntax Guidelines
553
555 Portions of this text are reprinted and reproduced in electronic form
556 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
557 -- Portable Operating System Interface (POSIX), The Open Group Base
558 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
559 cal and Electronics Engineers, Inc and The Open Group. (This is
560 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
561 event of any discrepancy between this version and the original IEEE and
562 The Open Group Standard, the original IEEE and The Open Group Standard
563 is the referee document. The original Standard can be obtained online
564 at http://www.unix.org/online.html .
565 Any typographical or formatting errors that appear in this page are
567 most likely to have been introduced during the conversion of the source
568 files to man page format. To report such errors, see https://www.ker‐
569 nel.org/doc/man-pages/reporting_bugs.html .
570IEEE/The Open Group 2013 M4(1P)