1M4(1P)                     POSIX Programmer's Manual                    M4(1P)
2
3
4

PROLOG

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

NAME

12       m4 — macro processor
13

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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
28       The following options shall be supported:
29
30       -s        Enable  line  synchronization output for the c99 preprocessor
31                 phase (that is, #line directives).
32
33       -D name[=val]
34                 Define name to val or to null if =val is omitted.
35
36       -U name   Undefine name.
37

OPERANDS

39       The following operand shall be supported:
40
41       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

STDIN

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

INPUT FILES

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

ENVIRONMENT VARIABLES

52       The following environment variables shall affect the execution of m4:
53
54       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
60       LC_ALL    If set to a non-empty string value, override  the  values  of
61                 all the other internationalization variables.
62
63       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
68       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
73       NLSPATH   Determine the location of message catalogs for the processing
74                 of LC_MESSAGES.
75

ASYNCHRONOUS EVENTS

77       Default.
78

STDOUT

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

STDERR

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

OUTPUT FILES

89       None.
90

EXTENDED DESCRIPTION

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
100       Macro calls have the form:
101
102
103           name(arg1, arg2, ..., argn)
104
105       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
109       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
114       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
122       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
133       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
137       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
143       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
148       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
159       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
170       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
180       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
186       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
194       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
199       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
211       divnum    The  defining text of the divnum macro shall be the number of
212                 the current output stream as a string.
213
214       dnl       The dnl macro shall cause m4 to discard all input  characters
215                 up to and including the next <newline>.
216
217       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
221       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
225       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
232
233                     ()
234                     unary +
235                     unary -
236                     ~
237
238                     !
239                     binary *
240                     /
241                     %
242                     binary +
243                     binary -
244                     <<
245                     >>
246                     <
247                     <=
248                     >
249                     >=
250                     ==
251                     !=
252                     binary &
253                     ^
254                     |
255                     &&
256                     ||
257
258                 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
270       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
276       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
290       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
295       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
301       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
308       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
312       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
321       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
327       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
332       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
344       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
350       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
356       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
362       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
367       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
380       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
389       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
393       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
398       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
402       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
416       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
421       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

EXIT STATUS

430       The following exit values shall be returned:
431
432        0    Successful completion.
433
434       >0    An error occurred
435
436       If  the  m4exit  macro  is used, the exit value can be specified by the
437       input file.
438

CONSEQUENCES OF ERRORS

440       Default.
441
442       The following sections are informative.
443

APPLICATION USAGE

445       The defn macro is useful for renaming macros, especially built-ins.
446
447       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
462       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
469       Applications should use the mkstemp macro instead  of  the  obsolescent
470       maketemp macro for creating temporary files.
471

EXAMPLES

473       If the file m4src contains the lines:
474
475
476           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
482       then the command
483
484
485           m4 m4src
486
487       or the command:
488
489
490           m4 -U VER m4src
491
492       produces the output:
493
494
495           The value of VER is "VER".
496           VER is not defined.
497
498           VER is not 2.
499           end
500
501       The command:
502
503
504           m4 -D VER m4src
505
506       produces the output:
507
508
509           The value of VER is "".
510           VER is defined to be .
511
512           VER is not 2.
513           end
514
515       The command:
516
517
518           m4 -D VER=1 m4src
519
520       produces the output:
521
522
523           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
529       The command:
530
531
532           m4 -D VER=2 m4src
533
534       produces the output:
535
536
537           The value of VER is "2".
538           VER is defined to be 2.
539
540           VER is 2.
541           end
542

RATIONALE

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
551       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

FUTURE DIRECTIONS

556       None.
557

SEE ALSO

559       c99
560
561       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
575       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 .
579
580
581
582IEEE/The Open Group                  2017                               M4(1P)
Impressum