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