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 (DEVELOPMENT)
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       IEEE Std 1003.1-2001,  Section  12.2, Utility Syntax Guidelines, except
25       that the order of the -D and -U options shall be significant.
26
27       The following options shall be supported:
28
29       -s     Enable line synchronization  output  for  the  c99  preprocessor
30              phase (that is, #line directives).
31
32       -D  name[=val]
33
34              Define name to val or to null if = val is omitted.
35
36       -U  name
37              Undefine name.
38
39

OPERANDS

41       The following operand shall be supported:
42
43       file   A  pathname of a text file to be processed. If no file is given,
44              or if it is '-', the standard input shall be read.
45
46

STDIN

48       The standard input shall be a text file that is used if no file operand
49       is given, or if it is '-' .
50

INPUT FILES

52       The input file named by the file operand shall be a text file.
53

ENVIRONMENT VARIABLES

55       The following environment variables shall affect the execution of m4:
56
57       LANG   Provide  a  default value for the internationalization variables
58              that are unset or null. (See  the  Base  Definitions  volume  of
59              IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari‐
60              ables for the precedence of internationalization variables  used
61              to determine the values of locale categories.)
62
63       LC_ALL If  set  to a non-empty string value, override the values of all
64              the other internationalization variables.
65
66       LC_CTYPE
67              Determine the locale for  the  interpretation  of  sequences  of
68              bytes  of  text  data as characters (for example, single-byte as
69              opposed to multi-byte characters in arguments and input files).
70
71       LC_MESSAGES
72              Determine the locale that should be used to  affect  the  format
73              and contents of diagnostic messages written to standard error.
74
75       NLSPATH
76              Determine the location of message catalogs for the processing of
77              LC_MESSAGES .
78
79

ASYNCHRONOUS EVENTS

81       Default.
82

STDOUT

84       The standard output shall be the same as the input files,  after  being
85       processed for macro expansion.
86

STDERR

88       The  standard  error shall be used to display strings with the errprint
89       macro, macro tracing enabled by the traceon macro, the defined text for
90       macros written by the dumpdef macro, or for diagnostic messages.
91

OUTPUT FILES

93       None.
94

EXTENDED DESCRIPTION

96       The  m4 utility shall compare each token from the input against the set
97       of built-in and user-defined macros. If the token matches the name of a
98       macro,  then  the token shall be replaced by the macro's defining text,
99       if any, and rescanned for matching macro names. Once no portion of  the
100       token matches the name of a macro, it shall be written to standard out‐
101       put. Macros may have arguments, in which case the  arguments  shall  be
102       substituted into the defining text before it is rescanned.
103
104       Macro calls have the form:
105
106
107              name(arg1, arg2, ..., argn)
108
109       Macro  names  shall  consist of letters, digits, and underscores, where
110       the first character is not a digit. Tokens not of this form  shall  not
111       be treated as macros.
112
113       The application shall ensure that the left parenthesis immediately fol‐
114       lows the name of the macro. If a token matching the name of a macro  is
115       not  followed  by  a  left  parenthesis, it is handled as a use of that
116       macro without arguments.
117
118       If a macro name is followed by a left parenthesis,  its  arguments  are
119       the  comma-separated tokens between the left parenthesis and the match‐
120       ing right parenthesis. Unquoted <blank>s and <newline>s preceding  each
121       argument  shall  be  ignored.  All other characters, including trailing
122       <blank>s and <newline>s, are retained.  Commas  enclosed  between  left
123       and right parenthesis characters do not delimit arguments.
124
125       Arguments  are  positionally defined and referenced. The string "$1" in
126       the defining text shall be replaced  by  the  first  argument.  Systems
127       shall  support at least nine arguments; only the first nine can be ref‐
128       erenced, using the strings "$1" to "$9", inclusive. The string "$0"  is
129       replaced with the name of the macro. The string "$#" is replaced by the
130       number of arguments as a string. The string "$*" is replaced by a  list
131       of  all  of  the  arguments,  separated  by commas.  The string "$@" is
132       replaced by a list of all of the arguments  separated  by  commas,  and
133       each  argument  is  quoted  using  the  current  left and right quoting
134       strings.
135
136       If fewer arguments are supplied than are in the macro  definition,  the
137       omitted  arguments  are  taken  to  be null. It is not an error if more
138       arguments are supplied than are in the macro definition.
139
140       No special meaning is given to any characters enclosed between matching
141       left  and right quoting strings, but the quoting strings are themselves
142       discarded. By default, the left quoting  string  consists  of  a  grave
143       accent ( '`' ) and the right quoting string consists of an acute accent
144       ( '" ); see also the changequote macro.
145
146       Comments are written but not  scanned  for  matching  macro  names;  by
147       default, the begin-comment string consists of the number sign character
148       and the end-comment string  consists  of  a  <newline>.  See  also  the
149       changecom and dnl macros.
150
151       The  m4  utility  shall  make  available the following built-in macros.
152       They can be redefined, but once this is done the  original  meaning  is
153       lost.  Their  values  shall  be  null  unless  otherwise stated. In the
154       descriptions below, the term defining text refers to the value  of  the
155       macro:  the  second  argument  to the define macro, among other things.
156       Except for the first argument to the eval macro, all numeric  arguments
157       to  built-in  macros shall be interpreted as decimal values. The string
158       values produced as the defining text of the decr, divnum, incr,  index,
159       len,  and sysval built-in macros shall be in the form of a decimal-con‐
160       stant as defined in the C language.
161
162       changecom
163              The changecom macro shall set the begin-comment and  end-comment
164              strings.  With no arguments, the comment mechanism shall be dis‐
165              abled. With a single argument, that argument  shall  become  the
166              begin-comment string and the <newline> shall become the end-com‐
167              ment string. With two arguments, the first argument shall become
168              the  begin-comment  string  and the second argument shall become
169              the end-comment string. Systems shall support comment strings of
170              at least five characters.
171
172       changequote
173              The  changequote  macro  shall set the begin-quote and end-quote
174              strings. With no arguments, the quote strings shall  be  set  to
175              the  default  values (that is, `'). With a single argument, that
176              argument shall become the begin-quote string and  the  <newline>
177              shall become the end-quote string. With two arguments, the first
178              argument shall become the  begin-quote  string  and  the  second
179              argument  shall  become the end-quote string. Systems shall sup‐
180              port quote strings of at least five characters.
181
182       decr   The defining text of the decr macro shall be its first  argument
183              decremented  by  1.  It shall be an error to specify an argument
184              containing any non-numeric characters.
185
186       define The second argument shall become the defining text of the  macro
187              whose name is the first argument.
188
189       defn   The  defining text of the defn macro shall be the quoted defini‐
190              tion (using the current quoting strings) of its arguments.
191
192       divert The m4 utility maintains nine temporary buffers, numbered  1  to
193              9, inclusive. When the last of the input has been processed, any
194              output that has been placed in these buffers shall be written to
195              standard  output  in  buffer-numerical  order.  The divert macro
196              shall divert future output to the buffer specified by its  argu‐
197              ment.  Specifying  no  argument or an argument of 0 shall resume
198              the normal output process. Output diverted  to  a  stream  other
199              than  0 to 9 shall be discarded. It shall be an error to specify
200              an argument containing any non-numeric characters.
201
202       divnum The defining text of the divnum macro shall be the number of the
203              current output stream as a string.
204
205       dnl    The  dnl macro shall cause m4 to discard all input characters up
206              to and including the next <newline>.
207
208       dumpdef
209              The dumpdef macro shall write the defined text to standard error
210              for  each  of the macros specified as arguments, or, if no argu‐
211              ments are specified, for all macros.
212
213       errprint
214              The errprint macro shall write its arguments to standard error.
215
216       eval   The eval macro shall evaluate its first argument  as  an  arith‐
217              metic  expression,  using 32-bit signed integer arithmetic.  All
218              of the C-language operators shall be supported, except for:
219
220
221              []
222              ->
223              ++
224              --
225              (type)
226              unary *
227              sizeof,
228              .
229              ?:
230              unary &
231
232       and all assignment operators. It shall be an error to  specify  any  of
233       these  operators. Precedence and associativity shall be as in the ISO C
234       standard. Systems shall support octal and hexadecimal numbers as in the
235       ISO C  standard. The second argument, if specified, shall set the radix
236       for the result; the default is 10.  The third argument,  if  specified,
237       sets  the  minimum number of digits in the result. It shall be an error
238       to specify the second or  third  argument  containing  any  non-numeric
239       characters.
240
241       ifdef  If  the first argument to the ifdef macro is defined, the defin‐
242              ing text shall be the second argument. Otherwise,  the  defining
243              text  shall  be  the  third  argument, if specified, or the null
244              string, if not.
245
246       ifelse The ifelse macro takes three or more arguments. If the first two
247              arguments  compare  as  equal  strings (after macro expansion of
248              both arguments), the defining text shall be the third  argument.
249              If  the  first two arguments do not compare as equal strings and
250              there are three arguments, the defining text shall be  null.  If
251              the  first  two  arguments  do  not compare as equal strings and
252              there are four or five arguments, the defining text shall be the
253              fourth  argument.  If  the first two arguments do not compare as
254              equal strings and there are six or  more  arguments,  the  first
255              three  arguments shall be discarded and processing shall restart
256              with the remaining arguments.
257
258       include
259              The defining text for the include macro shall be the contents of
260              the  file  named  by the first argument. It shall be an error if
261              the file cannot be read.
262
263       incr   The defining text of the incr macro shall be its first  argument
264              incremented  by  1.  It shall be an error to specify an argument
265              containing any non-numeric characters.
266
267       index  The defining text of the index macro shall be the first  charac‐
268              ter  position (as a string) in the first argument where a string
269              matching the second argument begins (zero origin), or -1 if  the
270              second argument does not occur.
271
272       len    The  defining  text  of  the len macro shall be the length (as a
273              string) of the first argument.
274
275       m4exit Exit from the m4 utility. If the first argument is specified, it
276              is  the  exit code. The default is zero. It shall be an error to
277              specify an argument containing any non-numeric characters.
278
279       m4wrap The first argument shall be processed when EOF  is  reached.  If
280              the m4wrap macro is used multiple times, the arguments specified
281              shall be processed in the order in which the m4wrap macros  were
282              processed.
283
284       maketemp
285              The defining text shall be the first argument, with any trailing
286              'X' characters replaced with the current process ID as a string.
287
288       popdef The popdef macro shall delete  the  current  definition  of  its
289              arguments,  replacing that definition with the previous one.  If
290              there is no previous definition, the macro is undefined.
291
292       pushdef
293              The pushdef macro shall be equivalent to the define  macro  with
294              the  exception that it shall preserve any current definition for
295              future retrieval using the popdef macro.
296
297       shift  The defining text for the shift macro shall be all of its  argu‐
298              ments except for the first one.
299
300       sinclude
301              The  sinclude  macro  shall  be equivalent to the include macro,
302              except that it shall not be an error if the file  is  inaccessi‐
303              ble.
304
305       substr The defining text for the substr macro shall be the substring of
306              the first argument beginning at the zero-offset character  posi‐
307              tion  specified  by  the second argument. The third argument, if
308              specified, shall be the number of characters to select;  if  not
309              specified,  the characters from the starting point to the end of
310              the first argument shall become the defining text. It shall  not
311              be  an  error  to specify a starting point beyond the end of the
312              first argument and the defining text shall be null. It shall  be
313              an error to specify an argument containing any non-numeric char‐
314              acters.
315
316       syscmd The syscmd macro shall interpret its first argument as  a  shell
317              command  line.  The  defining text shall be the string result of
318              that command. No output redirection shall be performed by the m4
319              utility. The exit status value from the command can be retrieved
320              using the sysval macro.
321
322       sysval The defining text of the sysval macro shall be the exit value of
323              the utility last invoked by the syscmd macro (as a string).
324
325       traceon
326              The  traceon macro shall enable tracing for the macros specified
327              as arguments, or, if no arguments are specified, for all macros.
328              The  trace  output  shall  be  written  to  standard error in an
329              unspecified format.
330
331       traceoff
332              The traceoff macro shall disable tracing for the  macros  speci‐
333              fied  as  arguments,  or, if no arguments are specified, for all
334              macros.
335
336       translit
337              The defining text of the translit macro shall be the first argu‐
338              ment  with  every  character  that occurs in the second argument
339              replaced with the corresponding character from the  third  argu‐
340              ment.
341
342       undefine
343              The undefine macro shall delete all definitions (including those
344              preserved using the pushdef macro) of the macros  named  by  its
345              arguments.
346
347       undivert
348              The  undivert  macro shall cause immediate output of any text in
349              temporary buffers named as arguments, or all  temporary  buffers
350              if  no  arguments  are specified. Buffers can be undiverted into
351              other temporary buffers. Undiverting shall discard the  contents
352              of  the  temporary  buffer.  It  shall be an error to specify an
353              argument containing any non-numeric characters.
354
355

EXIT STATUS

357       The following exit values shall be returned:
358
359        0     Successful completion.
360
361       >0     An error occurred
362
363
364       If the m4exit macro is used, the exit value can  be  specified  by  the
365       input file.
366

CONSEQUENCES OF ERRORS

368       Default.
369
370       The following sections are informative.
371

APPLICATION USAGE

373       The defn macro is useful for renaming macros, especially built-ins.
374

EXAMPLES

376       If the file m4src contains the lines:
377
378
379              The value of `VER' is "VER".
380              ifdef(`VER', "VER" is defined to be VER., VER is not defined.)
381              ifelse(VER, 1, "VER" is `VER'.)
382              ifelse(VER, 2, "VER" is `VER'., "VER" is not 2.)
383              end
384
385       then the command
386
387
388              m4 m4src
389
390       or the command:
391
392
393              m4 -U VER m4src
394
395       produces the output:
396
397
398              The value of VER is "VER".
399              VER is not defined.
400
401
402              VER is not 2.
403              end
404
405       The command:
406
407
408              m4 -D VER m4src
409
410       produces the output:
411
412
413              The value of VER is "".
414              VER is defined to be .
415
416
417              VER is not 2.
418              end
419
420       The command:
421
422
423              m4 -D VER=1 m4src
424
425       produces the output:
426
427
428              The value of VER is "1".
429              VER is defined to be 1.
430              VER is 1.
431              VER is not 2.
432              end
433
434       The command:
435
436
437              m4 -D VER=2 m4src
438
439
440              produces the output:
441              The value of VER is "2".
442              VER is defined to be 2.
443
444
445              VER is 2.
446              end
447

RATIONALE

449       None.
450

FUTURE DIRECTIONS

452       None.
453

SEE ALSO

455       c99
456
458       Portions  of  this text are reprinted and reproduced in electronic form
459       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
460       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
461       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
462       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
463       event of any discrepancy between this version and the original IEEE and
464       The  Open Group Standard, the original IEEE and The Open Group Standard
465       is the referee document. The original Standard can be  obtained  online
466       at http://www.opengroup.org/unix/online.html .
467
468
469
470IEEE/The Open Group                  2003                               M4(1P)
Impressum