1M4(P) POSIX Programmer's Manual M4(P)
2
6 m4 - macro processor (DEVELOPMENT)
7
9 m4 [-s][-D name[=val]]...[-U name]... file...
10
12 The m4 utility is a macro processor that shall read one or more text
13 files, process them according to their included macro statements, and
14 write the results to standard output.
15
17 The m4 utility shall conform to the Base Definitions volume of
18 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines, except
19 that the order of the -D and -U options shall be significant.
20 The following options shall be supported:
22 -s Enable line synchronization output for the c99 preprocessor
24 phase (that is, #line directives).
25 -D name[=val]
27 Define name to val or to null if = val is omitted.
29 -U name
31 Undefine name.
32
35 The following operand shall be supported:
36 file A pathname of a text file to be processed. If no file is given,
38 or if it is '-' , the standard input shall be read.
39
42 The standard input shall be a text file that is used if no file operand
43 is given, or if it is '-' .
44
46 The input file named by the file operand shall be a text file.
47
49 The following environment variables shall affect the execution of m4:
50 LANG Provide a default value for the internationalization variables
52 that are unset or null. (See the Base Definitions volume of
53 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
54 ables for the precedence of internationalization variables used
55 to determine the values of locale categories.)
56 LC_ALL If set to a non-empty string value, override the values of all
58 the other internationalization variables.
59 LC_CTYPE
61 Determine the locale for the interpretation of sequences of
62 bytes of text data as characters (for example, single-byte as
63 opposed to multi-byte characters in arguments and input files).
64 LC_MESSAGES
66 Determine the locale that should be used to affect the format
67 and contents of diagnostic messages written to standard error.
68 NLSPATH
70 Determine the location of message catalogs for the processing of
71 LC_MESSAGES .
72
75 Default.
76
78 The standard output shall be the same as the input files, after being
79 processed for macro expansion.
80
82 The standard error shall be used to display strings with the errprint
83 macro, macro tracing enabled by the traceon macro, the defined text for
84 macros written by the dumpdef macro, or for diagnostic messages.
85
87 None.
88
90 The m4 utility shall compare each token from the input against the set
91 of built-in and user-defined macros. If the token matches the name of a
92 macro, then the token shall be replaced by the macro's defining text,
93 if any, and rescanned for matching macro names. Once no portion of the
94 token matches the name of a macro, it shall be written to standard out‐
95 put. Macros may have arguments, in which case the arguments shall be
96 substituted into the defining text before it is rescanned.
97 Macro calls have the form:
99 name(arg1, arg2, ..., argn)
102 Macro names shall consist of letters, digits, and underscores, where
104 the first character is not a digit. Tokens not of this form shall not
105 be treated as macros.
106 The application shall ensure that the left parenthesis immediately fol‐
108 lows the name of the macro. If a token matching the name of a macro is
109 not followed by a left parenthesis, it is handled as a use of that
110 macro without arguments.
111 If a macro name is followed by a left parenthesis, its arguments are
113 the comma-separated tokens between the left parenthesis and the match‐
114 ing right parenthesis. Unquoted <blank>s and <newline>s preceding each
115 argument shall be ignored. All other characters, including trailing
116 <blank>s and <newline>s, are retained. Commas enclosed between left
117 and right parenthesis characters do not delimit arguments.
118 Arguments are positionally defined and referenced. The string "$1" in
120 the defining text shall be replaced by the first argument. Systems
121 shall support at least nine arguments; only the first nine can be ref‐
122 erenced, using the strings "$1" to "$9" , inclusive. The string "$0" is
123 replaced with the name of the macro. The string "$#" is replaced by the
124 number of arguments as a string. The string "$*" is replaced by a list
125 of all of the arguments, separated by commas. The string "$@" is
126 replaced by a list of all of the arguments separated by commas, and
127 each argument is quoted using the current left and right quoting
128 strings.
129 If fewer arguments are supplied than are in the macro definition, the
131 omitted arguments are taken to be null. It is not an error if more
132 arguments are supplied than are in the macro definition.
133 No special meaning is given to any characters enclosed between matching
135 left and right quoting strings, but the quoting strings are themselves
136 discarded. By default, the left quoting string consists of a grave
137 accent ( '`' ) and the right quoting string consists of an acute accent
138 ( '" ); see also the changequote macro.
139 Comments are written but not scanned for matching macro names; by
141 default, the begin-comment string consists of the number sign character
142 and the end-comment string consists of a <newline>. See also the
143 changecom and dnl macros.
144 The m4 utility shall make available the following built-in macros.
146 They can be redefined, but once this is done the original meaning is
147 lost. Their values shall be null unless otherwise stated. In the
148 descriptions below, the term defining text refers to the value of the
149 macro: the second argument to the define macro, among other things.
150 Except for the first argument to the eval macro, all numeric arguments
151 to built-in macros shall be interpreted as decimal values. The string
152 values produced as the defining text of the decr, divnum, incr, index,
153 len, and sysval built-in macros shall be in the form of a decimal-con‐
154 stant as defined in the C language.
155 changecom
157 The changecom macro shall set the begin-comment and end-comment
158 strings. With no arguments, the comment mechanism shall be dis‐
159 abled. With a single argument, that argument shall become the
160 begin-comment string and the <newline> shall become the end-com‐
161 ment string. With two arguments, the first argument shall become
162 the begin-comment string and the second argument shall become
163 the end-comment string. Systems shall support comment strings of
164 at least five characters.
165 changequote
167 The changequote macro shall set the begin-quote and end-quote
168 strings. With no arguments, the quote strings shall be set to
169 the default values (that is, `'). With a single argument, that
170 argument shall become the begin-quote string and the <newline>
171 shall become the end-quote string. With two arguments, the first
172 argument shall become the begin-quote string and the second
173 argument shall become the end-quote string. Systems shall sup‐
174 port quote strings of at least five characters.
175 decr The defining text of the decr macro shall be its first argument
177 decremented by 1. It shall be an error to specify an argument
178 containing any non-numeric characters.
179 define The second argument shall become the defining text of the macro
181 whose name is the first argument.
182 defn The defining text of the defn macro shall be the quoted defini‐
184 tion (using the current quoting strings) of its arguments.
185 divert The m4 utility maintains nine temporary buffers, numbered 1 to
187 9, inclusive. When the last of the input has been processed, any
188 output that has been placed in these buffers shall be written to
189 standard output in buffer-numerical order. The divert macro
190 shall divert future output to the buffer specified by its argu‐
191 ment. Specifying no argument or an argument of 0 shall resume
192 the normal output process. Output diverted to a stream other
193 than 0 to 9 shall be discarded. It shall be an error to specify
194 an argument containing any non-numeric characters.
195 divnum The defining text of the divnum macro shall be the number of the
197 current output stream as a string.
198 dnl The dnl macro shall cause m4 to discard all input characters up
200 to and including the next <newline>.
201 dumpdef
203 The dumpdef macro shall write the defined text to standard error
204 for each of the macros specified as arguments, or, if no argu‐
205 ments are specified, for all macros.
206 errprint
208 The errprint macro shall write its arguments to standard error.
209 eval The eval macro shall evaluate its first argument as an arith‐
211 metic expression, using 32-bit signed integer arithmetic. All
212 of the C-language operators shall be supported, except for:
213 []
216 ->
217 ++
218 --
219 (type)
220 unary *
221 sizeof,
222 .
223 ?:
224 unary &
225 and all assignment operators. It shall be an error to specify any of
227 these operators. Precedence and associativity shall be as in the ISO C
228 standard. Systems shall support octal and hexadecimal numbers as in the
229 ISO C standard. The second argument, if specified, shall set the radix
230 for the result; the default is 10. The third argument, if specified,
231 sets the minimum number of digits in the result. It shall be an error
232 to specify the second or third argument containing any non-numeric
233 characters.
234 ifdef If the first argument to the ifdef macro is defined, the defin‐
236 ing text shall be the second argument. Otherwise, the defining
237 text shall be the third argument, if specified, or the null
238 string, if not.
239 ifelse The ifelse macro takes three or more arguments. If the first two
241 arguments compare as equal strings (after macro expansion of
242 both arguments), the defining text shall be the third argument.
243 If the first two arguments do not compare as equal strings and
244 there are three arguments, the defining text shall be null. If
245 the first two arguments do not compare as equal strings and
246 there are four or five arguments, the defining text shall be the
247 fourth argument. If the first two arguments do not compare as
248 equal strings and there are six or more arguments, the first
249 three arguments shall be discarded and processing shall restart
250 with the remaining arguments.
251 include
253 The defining text for the include macro shall be the contents of
254 the file named by the first argument. It shall be an error if
255 the file cannot be read.
256 incr The defining text of the incr macro shall be its first argument
258 incremented by 1. It shall be an error to specify an argument
259 containing any non-numeric characters.
260 index The defining text of the index macro shall be the first charac‐
262 ter position (as a string) in the first argument where a string
263 matching the second argument begins (zero origin), or -1 if the
264 second argument does not occur.
265 len The defining text of the len macro shall be the length (as a
267 string) of the first argument.
268 m4exit Exit from the m4 utility. If the first argument is specified, it
270 is the exit code. The default is zero. It shall be an error to
271 specify an argument containing any non-numeric characters.
272 m4wrap The first argument shall be processed when EOF is reached. If
274 the m4wrap macro is used multiple times, the arguments specified
275 shall be processed in the order in which the m4wrap macros were
276 processed.
277 maketemp
279 The defining text shall be the first argument, with any trailing
280 'X' characters replaced with the current process ID as a string.
281 popdef The popdef macro shall delete the current definition of its
283 arguments, replacing that definition with the previous one. If
284 there is no previous definition, the macro is undefined.
285 pushdef
287 The pushdef macro shall be equivalent to the define macro with
288 the exception that it shall preserve any current definition for
289 future retrieval using the popdef macro.
290 shift The defining text for the shift macro shall be all of its argu‐
292 ments except for the first one.
293 sinclude
295 The sinclude macro shall be equivalent to the include macro,
296 except that it shall not be an error if the file is inaccessi‐
297 ble.
298 substr The defining text for the substr macro shall be the substring of
300 the first argument beginning at the zero-offset character posi‐
301 tion specified by the second argument. The third argument, if
302 specified, shall be the number of characters to select; if not
303 specified, the characters from the starting point to the end of
304 the first argument shall become the defining text. It shall not
305 be an error to specify a starting point beyond the end of the
306 first argument and the defining text shall be null. It shall be
307 an error to specify an argument containing any non-numeric char‐
308 acters.
309 syscmd The syscmd macro shall interpret its first argument as a shell
311 command line. The defining text shall be the string result of
312 that command. No output redirection shall be performed by the m4
313 utility. The exit status value from the command can be retrieved
314 using the sysval macro.
315 sysval The defining text of the sysval macro shall be the exit value of
317 the utility last invoked by the syscmd macro (as a string).
318 traceon
320 The traceon macro shall enable tracing for the macros specified
321 as arguments, or, if no arguments are specified, for all macros.
322 The trace output shall be written to standard error in an
323 unspecified format.
324 traceoff
326 The traceoff macro shall disable tracing for the macros speci‐
327 fied as arguments, or, if no arguments are specified, for all
328 macros.
329 translit
331 The defining text of the translit macro shall be the first argu‐
332 ment with every character that occurs in the second argument
333 replaced with the corresponding character from the third argu‐
334 ment.
335 undefine
337 The undefine macro shall delete all definitions (including those
338 preserved using the pushdef macro) of the macros named by its
339 arguments.
340 undivert
342 The undivert macro shall cause immediate output of any text in
343 temporary buffers named as arguments, or all temporary buffers
344 if no arguments are specified. Buffers can be undiverted into
345 other temporary buffers. Undiverting shall discard the contents
346 of the temporary buffer. It shall be an error to specify an
347 argument containing any non-numeric characters.
348
351 The following exit values shall be returned:
352 0 Successful completion.
354 >0 An error occurred
356 If the m4exit macro is used, the exit value can be specified by the
359 input file.
360
362 Default.
363 The following sections are informative.
365
367 The defn macro is useful for renaming macros, especially built-ins.
368
370 If the file m4src contains the lines:
371 The value of `VER' is "VER".
374 ifdef(`VER', "VER" is defined to be VER., VER is not defined.)
375 ifelse(VER, 1, "VER" is `VER'.)
376 ifelse(VER, 2, "VER" is `VER'., "VER" is not 2.)
377 end
378 then the command
380 m4 m4src
383 or the command:
385 m4 -U VER m4src
388 produces the output:
390 The value of VER is "VER".
393 VER is not defined.
394 VER is not 2.
397 end
398 The command:
400 m4 -D VER m4src
403 produces the output:
405 The value of VER is "".
408 VER is defined to be .
409 VER is not 2.
412 end
413 The command:
415 m4 -D VER=1 m4src
418 produces the output:
420 The value of VER is "1".
423 VER is defined to be 1.
424 VER is 1.
425 VER is not 2.
426 end
427 The command:
429 m4 -D VER=2 m4src
432 produces the output:
435 The value of VER is "2".
436 VER is defined to be 2.
437 VER is 2.
440 end
441
443 None.
444
446 None.
447
449 c99
450
452 Portions of this text are reprinted and reproduced in electronic form
453 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
454 -- Portable Operating System Interface (POSIX), The Open Group Base
455 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
456 Electrical and Electronics Engineers, Inc and The Open Group. In the
457 event of any discrepancy between this version and the original IEEE and
458 The Open Group Standard, the original IEEE and The Open Group Standard
459 is the referee document. The original Standard can be obtained online
460 at http://www.opengroup.org/unix/online.html .
461IEEE/The Open Group 2003 M4(P)