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
11

NAME

13       m4 — macro processor
14

SYNOPSIS

16       m4 [−s] [−D name[=val]]... [−U name]... file...
17

DESCRIPTION

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

OPTIONS

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

OPERANDS

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

STDIN

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

INPUT FILES

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

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

78       Default.
79

STDOUT

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

STDERR

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

OUTPUT FILES

90       None.
91

EXTENDED DESCRIPTION

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
101       Macro calls have the form:
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                     unary +
234                     unary −
235                     ~
236
237                     !
238                     binary *
239                     /
240                     %
241                     binary +
242                     binary −
243                     <<
244                     >>
245                     <
246                     <=
247                     >
248                     >=
249                     ==
250                     !=
251                     binary &
252                     ^
253                     |
254                     &&
255                     ||
256
257                 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
269       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
275       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
289       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
294       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
300       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
307       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
311       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
316       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
322       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
327       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
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           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
481       then the command
482
483           m4 m4src
484
485       or the command:
486
487           m4 −U VER m4src
488
489       produces the output:
490
491           The value of VER is "VER".
492           VER is not defined.
493
494           VER is not 2.
495           end
496
497       The command:
498
499           m4 −D VER m4src
500
501       produces the output:
502
503           The value of VER is "".
504           VER is defined to be .
505
506           VER is not 2.
507           end
508
509       The command:
510
511           m4 −D VER=1 m4src
512
513       produces the output:
514
515           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
521       The command:
522
523           m4 −D VER=2 m4src
524
525       produces the output:
526
527           The value of VER is "2".
528           VER is defined to be 2.
529
530           VER is 2.
531           end
532

RATIONALE

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

FUTURE DIRECTIONS

546       None.
547

SEE ALSO

549       c99
550
551       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
566       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 .
570
571
572
573IEEE/The Open Group                  2013                               M4(1P)
Impressum