1M4(1P) POSIX Programmer's Manual M4(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 m4 - macro processor (DEVELOPMENT)
13
15 m4 [-s][-D name[=val]]...[-U name]... file...
16
18 The m4 utility is a macro processor that shall read one or more text
19 files, process them according to their included macro statements, and
20 write the results to standard output.
21
23 The m4 utility shall conform to the Base Definitions volume of
24 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 The following options shall be supported:
28 -s Enable line synchronization output for the c99 preprocessor
30 phase (that is, #line directives).
31 -D name[=val]
33 Define name to val or to null if = val is omitted.
35 -U name
37 Undefine name.
38
41 The following operand shall be supported:
42 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
48 The standard input shall be a text file that is used if no file operand
49 is given, or if it is '-' .
50
52 The input file named by the file operand shall be a text file.
53
55 The following environment variables shall affect the execution of m4:
56 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 LC_ALL If set to a non-empty string value, override the values of all
64 the other internationalization variables.
65 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 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 NLSPATH
76 Determine the location of message catalogs for the processing of
77 LC_MESSAGES .
78
81 Default.
82
84 The standard output shall be the same as the input files, after being
85 processed for macro expansion.
86
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
93 None.
94
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 Macro calls have the form:
105 name(arg1, arg2, ..., argn)
108 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 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 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 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 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 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 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 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 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 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 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 define The second argument shall become the defining text of the macro
187 whose name is the first argument.
188 defn The defining text of the defn macro shall be the quoted defini‐
190 tion (using the current quoting strings) of its arguments.
191 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 divnum The defining text of the divnum macro shall be the number of the
203 current output stream as a string.
204 dnl The dnl macro shall cause m4 to discard all input characters up
206 to and including the next <newline>.
207 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 errprint
214 The errprint macro shall write its arguments to standard error.
215 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 []
222 ->
223 ++
224 --
225 (type)
226 unary *
227 sizeof,
228 .
229 ?:
230 unary &
231 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 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 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 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 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 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 len The defining text of the len macro shall be the length (as a
273 string) of the first argument.
274 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 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 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 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 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 shift The defining text for the shift macro shall be all of its argu‐
298 ments except for the first one.
299 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 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 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 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 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 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 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 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 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
357 The following exit values shall be returned:
358 0 Successful completion.
360 >0 An error occurred
362 If the m4exit macro is used, the exit value can be specified by the
365 input file.
366
368 Default.
369 The following sections are informative.
371
373 The defn macro is useful for renaming macros, especially built-ins.
374
376 If the file m4src contains the lines:
377 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 then the command
386 m4 m4src
389 or the command:
391 m4 -U VER m4src
394 produces the output:
396 The value of VER is "VER".
399 VER is not defined.
400 VER is not 2.
403 end
404 The command:
406 m4 -D VER m4src
409 produces the output:
411 The value of VER is "".
414 VER is defined to be .
415 VER is not 2.
418 end
419 The command:
421 m4 -D VER=1 m4src
424 produces the output:
426 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 The command:
435 m4 -D VER=2 m4src
438 produces the output:
441 The value of VER is "2".
442 VER is defined to be 2.
443 VER is 2.
446 end
447
449 None.
450
452 None.
453
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 .
467IEEE/The Open Group 2003 M4(1P)