1 .\" $NetBSD: m4.1,v 1.23 2012/04/08 22:00:39 wiz Exp $
2 .\" @(#) $OpenBSD: m4.1,v 1.59 2010/10/21 13:20:51 jmc Exp $
4 .\" Copyright (c) 1989, 1993
5 .\" The Regents of the University of California. All rights reserved.
7 .\" This code is derived from software contributed to Berkeley by
8 .\" Ozan Yigit at York University.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
41 .Nd macro language processor
47 .Fl D Ar name Op No = Ar value
59 utility is a macro processor that can be used as a front end to any
60 language (e.g., C, ratfor, fortran, lex, and yacc).
61 If no input files are given,
63 reads from the standard input,
64 otherwise files specified on the command line are
65 processed in the given order.
66 Input files can be regular files, files in the m4 include paths, or a
69 denoting standard input.
72 the processed text to the standard output, unless told otherwise.
74 Macro calls have the form name(argument1[, argument2, ..., argumentN]).
76 There cannot be any space following the macro name and the open
79 If the macro name is not followed by an open
80 parenthesis it is processed with no arguments.
82 Macro names consist of a leading alphabetic or underscore
83 possibly followed by alphanumeric or underscore characters, e.g.,
84 valid macro names match the pattern
85 .Dq [a-zA-Z_][a-zA-Z0-9_]* .
87 In arguments to macros, leading unquoted space, tab, and newline
89 characters are ignored.
90 To quote strings, use left and right single quotes
92 .Sq "\ this is a string with a leading space"
94 You can change the quote characters with the
98 Most built-ins don't make any sense without arguments, and hence are not
99 recognized as special when not followed by an open parenthesis.
101 The options are as follows:
103 .It Fl D Ns Ar name Ns Op Pf = Ns Ar value
106 to have some value (or
111 may hold the following:
114 print macro arguments.
116 print macro expansion over several lines.
118 print result of macro expansion.
120 print filename location.
124 quote arguments and expansion with the current quotes.
126 start with all macros traced.
128 number macro expansions.
133 By default, trace is set to
136 Activate GNU-m4 compatibility mode.
137 In this mode, translit handles simple character
138 ranges (e.g., a-z), regular expressions mimic emacs behavior,
139 multiple m4wrap calls are handled as a stack,
140 the number of diversions is unlimited,
141 empty names for macro definitions are allowed,
145 .It Fl I Ar "dirname"
153 Prefix all built-in macros with
155 For example, instead of writing
160 Output line synchronization directives, suitable for
165 .It Fl "U" Ns Ar "name"
171 provides the following built-in macros.
172 They may be redefined, losing their original meaning.
173 Return values are null unless otherwise stated.
174 .Bl -tag -width changequote
176 Calls a built-in by its
178 overriding possible redefinitions.
179 .It Fn changecom startcomment endcomment
180 Changes the start comment and end comment sequences.
181 Comment sequences may be up to five characters long.
182 The default values are the hash sign
183 and the newline character.
184 .Bd -literal -offset indent
188 With no arguments, comments are turned off.
189 With one single argument, the end comment sequence is set
190 to the newline character.
191 .It Fn changequote beginquote endquote
192 Defines the open quote and close quote sequences.
193 Quote sequences may be up to five characters long.
194 The default values are the backquote character and the quote
196 .Bd -literal -offset indent
197 `Here is a quoted string'
200 With no arguments, the default quotes are restored.
201 With one single argument, the close quote sequence is set
202 to the newline character.
204 Decrements the argument
209 must be a valid numeric string.
210 .It Fn define name value
211 Define a new macro named by the first argument
214 value of the second argument
220 is 0 through 9) is replaced by the
224 is the name of the calling macro.
225 Undefined arguments are replaced by a null string.
227 is replaced by the number of arguments;
229 is replaced by all arguments comma separated;
233 but all arguments are quoted against further expansion.
235 Returns the quoted definition for each argument.
236 This can be used to rename
237 macro definitions (even for built-in macros).
239 There are 10 output queues (numbered 0-9).
240 At the end of processing
242 concatenates all the queues in numerical order to produce the
244 Initially the output queue is 0.
246 macro allows you to select a new output queue (an invalid argument
247 passed to divert causes output to be discarded).
249 Returns the current output queue number.
251 Discard input characters up to and including the next newline.
252 .It Fn dumpdef name ...
253 Prints the names and definitions for the named items, or for everything
254 if no arguments are passed.
256 Prints the first argument on the standard error output stream.
258 Passes its first argument to a shell and returns the shell's standard output.
259 Note that the shell shares its standard input and standard error with
262 Computes the first argument as an arithmetic expression using 32-bit
264 Operators are the standard C ternary, arithmetic, logical,
265 shift, relational, bitwise, and parentheses operators.
267 octal, decimal, and hexadecimal numbers as in C.
268 The second argument (if any)
269 specifies the radix for the result and the third argument (if any)
270 specifies the minimum number of digits in the result.
274 .It Fn format formatstring arg1 ...
277 with escape sequences substituted with
279 and following arguments, in a way similar to
281 This built-in is only available in GNU-m4 compatibility mode, and the only
282 parameters implemented are there for autoconf compatibility:
283 left-padding flag, an optional field width, a maximum field width,
284 *-specified field widths, and the %s and %c data type.
285 .It Fn ifdef name yes no
286 If the macro named by the first argument is defined then return the second
287 argument, otherwise the third.
288 If there is no third argument, the value is
293 .It Fn ifelse a b yes ...
294 If the first argument
296 matches the second argument
303 If the match fails the three arguments are
304 discarded and the next three arguments are used until there is
305 zero or one arguments left, either this last argument or
307 is returned if no other matches were found.
309 Returns the contents of the file specified in the first argument.
310 If the file is not found as is, look through the include path:
311 first the directories specified with
313 on the command line, then the environment variable
315 as a colon-separated list of directories.
316 Include aborts with an error message if the file cannot be included.
318 Increments the argument by 1.
319 The argument must be a valid numeric string.
320 .It Fn index string substring
321 Returns the index of the second argument in the first argument (e.g.,
322 .Ic index(the quick brown fox jumped, fox)
325 argument is not found index returns \-1.
326 .It Fn indir macro arg1 ...
327 Indirectly calls the macro whose name is passed as the first argument,
328 with the remaining arguments passed as first, ... arguments.
330 Returns the number of characters in the first argument.
334 Immediately exits with the return value specified by the first argument,
337 Allows you to define what happens at the final
339 usually for cleanup purposes (e.g.,
340 .Ic m4wrap("cleanup(tempfile)")
341 causes the macro cleanup to be
342 invoked after all other processing is done).
346 get inserted in sequence at the final
348 .It Fn maketemp template
351 .It Fn mkstemp template
354 on the first argument, and returns the modified string.
355 This can be used to create unique
356 temporary file names.
358 Includes the contents of the file specified by the first argument without
359 any macro processing.
360 Aborts with an error message if the file cannot be
362 .It Fn patsubst string regexp replacement
363 Substitutes a regular expression in a string with a replacement string.
364 Usual substitution patterns apply: an ampersand
366 is replaced by the string matching the regular expression.
371 is a digit, is replaced by the corresponding back-reference.
372 .It Fn popdef arg ...
375 definition for each argument.
376 .It Fn pushdef macro def
377 Takes the same arguments as
379 but it saves the definition on a
380 stack for later retrieval by
382 .It Fn regexp string regexp replacement
383 Finds a regular expression in a string.
384 If no further arguments are given,
385 it returns the first match position or \-1 if no match.
387 is provided, it returns the replacement string, with sub-patterns replaced.
388 .It Fn shift arg1 ...
389 Returns all but the first argument, the remaining arguments are
390 quoted and pushed back with commas in between.
392 nullifies the effect of the extra scan that will subsequently be
397 except it ignores any errors.
401 except it ignores any errors.
402 .It Fn substr string offset length
403 Returns a substring of the first argument starting at the offset specified
404 by the second argument and the length specified by the third argument.
405 If no third argument is present it returns the rest of the string.
407 Passes the first argument to the shell.
410 Returns the return value from the last
412 .It Fn traceon arg ...
413 Enables tracing of macro expansions for the given arguments, or for all
414 macros if no argument is given.
415 .It Fn traceoff arg ...
416 Disables tracing of macro expansions for the given arguments, or for all
417 macros if no argument is given.
418 .It Fn translit string mapfrom mapto
419 Transliterate the characters in the first argument from the set
420 given by the second argument to the set given by the third.
424 .It Fn undefine name1 ...
425 Removes the definition for the macros specified by its arguments.
426 .It Fn undivert arg ...
427 Flushes the named output queues (or all queues if no arguments).
429 A pre-defined macro for testing the OS platform.
431 Returns the current file's line number.
433 Returns the current file's name.
440 macro can modify the exit status.
444 utility is mostly compliant with the
464 are extensions to that specification.
467 is not supposed to be a synonym for
469 but instead to be an insecure temporary file name creation function.
470 The change causes no known compatibility issues.
472 The output format of tracing and of
474 are not specified in any standard,
475 are likely to change and should not be relied upon.
476 The current format of tracing is closely modelled on
486 handle macro definitions as a stack.
489 interacts with the stack in an undefined way.
490 In this implementation,
492 replaces the top-most definition only.
493 Other implementations may erase all definitions on the stack instead.
495 All built-ins do expand without arguments in many other
500 have dire size limitations with respect to buffer sizes.
503 .An Ozan Yigit Aq oz@sis.yorku.ca
505 .An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU .
507 GNU-m4 compatibility extensions by
508 .An Marc Espie Aq espie@cvs.openbsd.org .