| blob | dbe5e34b981eee6f54e95ca513d2f4277fa44b40 |
1 .\" $NetBSD: m4.1,v 1.25 2014/01/07 13:32:21 wiz Exp $
2 .\" @(#) $OpenBSD: m4.1,v 1.56 2009/10/14 17:19:47 sthen Exp $
3 .\"
4 .\" Copyright (c) 1989, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" This code is derived from software contributed to Berkeley by
8 .\" Ozan Yigit at York University.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
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.
21 .\"
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
32 .\" SUCH DAMAGE.
33 .\"
34 .Dd January 7, 2014
35 .Dt M4 1
36 .Os
37 .Sh NAME
38 .Nm m4
39 .Nd macro language processor
40 .Sh SYNOPSIS
41 .Nm m4
42 .Op Fl gPs
43 .Oo
44 .Sm off
45 .Fl D Ar name Op No = Ar value
46 .Sm on
47 .Oc
48 .Op Fl d Ar flags
49 .Op Fl I Ar dirname
50 .Op Fl o Ar filename
51 .Op Fl t Ar macro
52 .Op Fl U Ns Ar name
53 .Op Ar
54 .Sh DESCRIPTION
55 The
56 .Nm m4
57 utility is a macro processor that can be used as a front end to any
58 language (e.g., C, ratfor, fortran, lex, and yacc).
59 If no input files are given,
60 .Nm m4
61 reads from the standard input,
62 otherwise files specified on the command line are
63 processed in the given order.
64 Input files can be regular files, files in the m4 include paths, or a
65 single dash
66 .Pq Sq - ,
67 denoting standard input.
68 .Nm m4
69 writes
70 the processed text to the standard output, unless told otherwise.
71 .Pp
72 Macro calls have the form name(argument1[, argument2, ..., argumentN]).
73 .Pp
74 There cannot be any space following the macro name and the open
75 parenthesis
76 .Sq \&( .
77 If the macro name is not followed by an open
78 parenthesis it is processed with no arguments.
79 .Pp
80 Macro names consist of a leading alphabetic or underscore
81 possibly followed by alphanumeric or underscore characters, e.g.,
82 valid macro names match the pattern
83 .Dq [a-zA-Z_][a-zA-Z0-9_]* .
84 .Pp
85 In arguments to macros, leading unquoted space, tab, and newline
86 .Pq Sq \en
87 characters are ignored.
88 To quote strings, use left and right single quotes
89 .Po e.g.,\ \&
90 .Sq "\ this is a string with a leading space"
91 .Pc .
92 You can change the quote characters with the
93 .Ic changequote
94 built-in macro.
95 .Pp
96 Most built-ins don't make any sense without arguments, and hence are not
97 recognized as special when not followed by an open parenthesis.
98 .Pp
99 The options are as follows:
100 .Bl -tag -width Ds
101 .It Fl D Ns Ar name Ns Op Pf = Ns Ar value
102 Define the symbol
103 .Ar name
104 to have some value (or
105 .Dv NULL ) .
106 .It Fl d Ar "flags"
107 Set trace flags.
108 .Ar flags
109 may hold the following:
110 .Bl -tag -width Ds
111 .It Ar a
112 print macro arguments.
113 .It Ar c
114 print macro expansion over several lines.
115 .It Ar e
116 print result of macro expansion.
117 .It Ar f
118 print filename location.
119 .It Ar l
120 print line number.
121 .It Ar q
122 quote arguments and expansion with the current quotes.
123 .It Ar t
124 start with all macros traced.
125 .It Ar x
126 number macro expansions.
127 .It Ar V
128 turn on all options.
129 .El
130 .Pp
131 By default, trace is set to
132 .Qq eq .
133 .It Fl g
134 Activate GNU-m4 compatibility mode.
135 In this mode, translit handles simple character
136 ranges (e.g., a-z), regular expressions mimic emacs behavior,
137 multiple m4wrap calls are handled as a stack,
138 the number of diversions is unlimited,
139 empty names for macro definitions are allowed,
140 and eval understands
141 .Sq 0rbase:value
142 numbers.
143 .It Fl I Ar "dirname"
144 Add directory
145 .Ar dirname
146 to the include path.
147 .It Fl o Ar filename
148 Send trace output to
149 .Ar filename .
150 .It Fl P
151 Prefix all built-in macros with
152 .Sq m4_ .
153 For example, instead of writing
154 .Ic define ,
155 use
156 .Ic m4_define .
157 .It Fl s
158 Output line synchronization directives, suitable for
159 .Xr cpp 1 .
160 .It Fl t Ar macro
161 Turn tracing on for
162 .Ar macro .
163 .It Fl "U" Ns Ar "name"
164 Undefine the symbol
165 .Ar name .
166 .El
167 .Sh SYNTAX
168 .Nm m4
169 provides the following built-in macros.
170 They may be redefined, losing their original meaning.
171 Return values are null unless otherwise stated.
172 .Bl -tag -width changequote
173 .It Fn builtin name
174 Calls a built-in by its
175 .Fa name ,
176 overriding possible redefinitions.
177 .It Fn changecom startcomment endcomment
178 Changes the start comment and end comment sequences.
179 Comment sequences may be up to five characters long.
180 The default values are the hash sign
181 and the newline character.
182 .Bd -literal -offset indent
183 # This is a comment
184 .Ed
185 .Pp
186 With no arguments, comments are turned off.
187 With one single argument, the end comment sequence is set
188 to the newline character.
189 .It Fn changequote beginquote endquote
190 Defines the open quote and close quote sequences.
191 Quote sequences may be up to five characters long.
192 The default values are the backquote character and the quote
193 character.
194 .Bd -literal -offset indent
195 `Here is a quoted string'
196 .Ed
197 .Pp
198 With no arguments, the default quotes are restored.
199 With one single argument, the close quote sequence is set
200 to the newline character.
201 .It Fn decr arg
202 Decrements the argument
203 .Fa arg
204 by 1.
205 The argument
206 .Fa arg
207 must be a valid numeric string.
208 .It Fn define name value
209 Define a new macro named by the first argument
210 .Fa name
211 to have the
212 value of the second argument
213 .Fa value .
214 Each occurrence of
215 .Sq $n
216 (where
217 .Ar n
218 is 0 through 9) is replaced by the
219 .Ar n Ns 'th
220 argument.
221 .Sq $0
222 is the name of the calling macro.
223 Undefined arguments are replaced by a null string.
224 .Sq $#
225 is replaced by the number of arguments;
226 .Sq $*
227 is replaced by all arguments comma separated;
228 .Sq $@
229 is the same as
230 .Sq $*
231 but all arguments are quoted against further expansion.
232 .It Fn defn name ...
233 Returns the quoted definition for each argument.
234 This can be used to rename
235 macro definitions (even for built-in macros).
236 .It Fn divert num
237 There are 10 output queues (numbered 0-9).
238 At the end of processing
239 .Nm m4
240 concatenates all the queues in numerical order to produce the
241 final output.
242 Initially the output queue is 0.
243 The divert
244 macro allows you to select a new output queue (an invalid argument
245 passed to divert causes output to be discarded).
246 .It Ic divnum
247 Returns the current output queue number.
248 .It Ic dnl
249 Discard input characters up to and including the next newline.
250 .It Fn dumpdef name ...
251 Prints the names and definitions for the named items, or for everything
252 if no arguments are passed.
253 .It Fn errprint msg
254 Prints the first argument on the standard error output stream.
255 .It Fn esyscmd cmd
256 Passes its first argument to a shell and returns the shell's standard output.
257 Note that the shell shares its standard input and standard error with
258 .Nm m4 .
259 .It Fn eval expr[,radix[,minimum]]
260 Computes the first argument as an arithmetic expression using 32-bit
261 arithmetic.
262 Operators are the standard C ternary, arithmetic, logical,
263 shift, relational, bitwise, and parentheses operators.
264 You can specify
265 octal, decimal, and hexadecimal numbers as in C.
266 The optional second argument
267 .Fa radix
268 specifies the radix for the result and the optional third argument
269 .Fa minimum
270 specifies the minimum number of digits in the result.
271 .It Fn expr expr
272 This is an alias for
273 .Ic eval .
274 .It Fn format formatstring arg1 ...
275 Returns
276 .Fa formatstring
277 with escape sequences substituted with
278 .Fa arg1
279 and following arguments, in a way similar to
280 .Xr printf 3 .
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
289 .Dv NULL .
290 The word
291 .Qq unix
292 is predefined.
293 .It Fn ifelse a b yes ...
294 If the first argument
295 .Fa a
296 matches the second argument
297 .Fa b
298 then
299 .Fn ifelse
300 returns
301 the third argument
302 .Fa yes .
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
306 .Dv NULL
307 is returned if no other matches were found.
308 .It Fn include name
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
312 .Fl I
313 on the command line, then the environment variable
314 .Ev M4PATH ,
315 as a colon-separated list of directories.
316 Include aborts with an error message if the file cannot be included.
317 .It Fn incr arg
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)
323 returns 16).
324 If the second
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.
329 .It Fn len arg
330 Returns the number of characters in the first argument.
331 Extra arguments
332 are ignored.
333 .It Fn m4exit code
334 Immediately exits with the return value specified by the first argument,
335 0 if none.
336 .It Fn m4wrap todo
337 Allows you to define what happens at the final
338 .Dv EOF ,
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).
343 .Pp
344 Multiple calls to
345 .Fn m4wrap
346 get inserted in sequence at the final
347 .Dv EOF .
348 .It Fn maketemp template
349 Invokes
350 .Xr mkstemp 3
351 on the first argument, and returns the modified string.
352 This can be used to create unique
353 temporary file names.
354 .It Fn paste file
355 Includes the contents of the file specified by the first argument without
356 any macro processing.
357 Aborts with an error message if the file cannot be
358 included.
359 .It Fn patsubst string regexp replacement
360 Substitutes a regular expression in a string with a replacement string.
361 Usual substitution patterns apply: an ampersand
362 .Pq Sq \&&
363 is replaced by the string matching the regular expression.
364 The string
365 .Sq \e# ,
366 where
367 .Sq #
368 is a digit, is replaced by the corresponding back-reference.
369 .It Fn popdef arg ...
370 Restores the
371 .Ic pushdef Ns ed
372 definition for each argument.
373 .It Fn pushdef macro def
374 Takes the same arguments as
375 .Ic define ,
376 but it saves the definition on a
377 stack for later retrieval by
378 .Fn popdef .
379 .It Fn regexp string regexp replacement
380 Finds a regular expression in a string.
381 If no further arguments are given,
382 it returns the first match position or \-1 if no match.
383 If a third argument
384 is provided, it returns the replacement string, with sub-patterns replaced.
385 .It Fn shift arg1 ...
386 Returns all but the first argument, the remaining arguments are
387 quoted and pushed back with commas in between.
388 The quoting
389 nullifies the effect of the extra scan that will subsequently be
390 performed.
391 .It Fn sinclude file
392 Similar to
393 .Ic include ,
394 except it ignores any errors.
395 .It Fn spaste file
396 Similar to
397 .Fn paste ,
398 except it ignores any errors.
399 .It Fn substr string offset length
400 Returns a substring of the first argument starting at the offset specified
401 by the second argument and the length specified by the third argument.
402 If no third argument is present it returns the rest of the string.
403 .It Fn syscmd cmd
404 Passes the first argument to the shell.
405 Nothing is returned.
406 .It Ic sysval
407 Returns the return value from the last
408 .Ic syscmd .
409 .It Fn traceon arg ...
410 Enables tracing of macro expansions for the given arguments, or for all
411 macros if no argument is given.
412 .It Fn traceoff arg ...
413 Disables tracing of macro expansions for the given arguments, or for all
414 macros if no argument is given.
415 .It Fn translit string mapfrom mapto
416 Transliterate the characters in the first argument from the set
417 given by the second argument to the set given by the third.
418 You cannot use
419 .Xr tr 1
420 style abbreviations.
421 .It Fn undefine name1 ...
422 Removes the definition for the macros specified by its arguments.
423 .It Fn undivert arg ...
424 Flushes the named output queues (or all queues if no arguments).
425 .It Ic unix
426 A pre-defined macro for testing the OS platform.
427 .It Ic __line__
428 Returns the current file's line number.
429 .It Ic __file__
430 Returns the current file's name.
431 .El
432 .Sh STANDARDS
433 The
434 .Nm
435 utility is compliant with the
436 .St -p1003.1-2008
437 specification.
438 .Pp
439 The flags
440 .Op Fl dgIot
441 and the macros
442 .Ic builtin ,
443 .Ic esyscmd ,
444 .Ic expr ,
445 .Ic format ,
446 .Ic indir ,
447 .Ic paste ,
448 .Ic patsubst ,
449 .Ic regexp ,
450 .Ic spaste ,
451 .Ic unix ,
452 .Ic __line__ ,
453 and
454 .Ic __file__
455 are extensions to that specification.
456 .Pp
457 The output format of tracing and of
458 .Ic dumpdef
459 are not specified in any standard,
460 are likely to change and should not be relied upon.
461 The current format of tracing is closely modelled on
462 .Nm gnu-m4 ,
463 to allow
464 .Nm autoconf
465 to work.
466 .Pp
467 The built-ins
468 .Ic pushdef
469 and
470 .Ic popdef
471 handle macro definitions as a stack.
472 However,
473 .Ic define
474 interacts with the stack in an undefined way.
475 In this implementation,
476 .Ic define
477 replaces the top-most definition only.
478 Other implementations may erase all definitions on the stack instead.
479 .Pp
480 All built-ins do expand without arguments in many other
481 .Nm m4 .
482 .Pp
483 Many other
484 .Nm
485 have dire size limitations with respect to buffer sizes.
486 .Sh AUTHORS
487 .An -nosplit
488 .An Ozan Yigit Aq Mt oz@sis.yorku.ca
489 and
490 .An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU .
491 .Pp
492 GNU-m4 compatibility extensions by
493 .An Marc Espie Aq Mt espie@cvs.openbsd.org .