Annotation of src/usr.bin/m4/m4.1, Revision 1.31
1.31 ! millert 1: .\" @(#) $OpenBSD: m4.1,v 1.30 2003/04/14 06:39:24 jmc Exp $
1.29 jmc 2: .\"
3: .\" Copyright (c) 1989, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 deraadt 5: .\"
1.29 jmc 6: .\" This code is derived from software contributed to Berkeley by
7: .\" Ozan Yigit at York University.
1.1 deraadt 8: .\"
1.29 jmc 9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
1.31 ! millert 17: .\" 3. Neither the name of the University nor the names of its contributors
1.29 jmc 18: .\" may be used to endorse or promote products derived from this software
19: .\" without specific prior written permission.
20: .\"
21: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31: .\" SUCH DAMAGE.
32: .\"
1.1 deraadt 33: .Dd January 26, 1993
1.5 aaron 34: .Dt M4 1
1.1 deraadt 35: .Os
36: .Sh NAME
37: .Nm m4
38: .Nd macro language processor
39: .Sh SYNOPSIS
40: .Nm m4
1.23 espie 41: .Op Fl d Ar flags
42: .Op Fl t Ar name
1.28 espie 43: .Op Fl o Ar filename
1.12 espie 44: .Op Fl g
1.25 espie 45: .Op Fl s
1.1 deraadt 46: .Oo
47: .Fl D Ns Ar name Ns Op Ar =value
48: .Oc
49: .Op Fl U Ns Ar name
1.7 espie 50: .Op Fl I Ar dirname
1.1 deraadt 51: .Sh DESCRIPTION
52: The
53: .Nm m4
54: utility is a macro processor that can be used as a front end to any
55: language (e.g., C, ratfor, fortran, lex, and yacc).
56: .Nm m4
57: reads from the standard input and writes
58: the processed text to the standard output.
59: .Pp
1.8 espie 60: Macro calls have the form name(argument1[, argument2, ..., argumentN]).
1.1 deraadt 61: .Pp
62: There cannot be any space following the macro name and the open
1.10 aaron 63: parenthesis
64: .Pq Ql ( .
65: If the macro name is not followed by an open
1.5 aaron 66: parenthesis it is processed with no arguments.
1.1 deraadt 67: .Pp
68: Macro names consist of a leading alphabetic or underscore
1.9 espie 69: possibly followed by alphanumeric or underscore characters, e.g.,
1.10 aaron 70: valid macro names match the pattern
71: .Dq [a-zA-Z_][a-zA-Z0-9_]* .
1.1 deraadt 72: .Pp
1.10 aaron 73: In arguments to macros, leading unquoted space, tab, and newline
74: .Pq Ql \en
75: characters are ignored.
76: To quote strings, use left and right single
77: quotes (e.g.,
1.27 mpech 78: .Ql "\ this is a string with a leading space" ) .
1.10 aaron 79: You can change the quote characters with the
1.5 aaron 80: .Ic changequote
81: built-in macro.
1.9 espie 82: .Pp
1.12 espie 83: Most built-ins don't make any sense without arguments, and hence are not
1.9 espie 84: recognized as special when not followed by an open parenthesis.
1.1 deraadt 85: .Pp
86: The options are as follows:
1.20 aaron 87: .Bl -tag -width Ds
1.1 deraadt 88: .It Fl D Ns Ar name Ns Oo
89: .Ar =value
90: .Oc
91: Define the symbol
92: .Ar name
1.10 aaron 93: to have some value (or
94: .Dv NULL ) .
1.1 deraadt 95: .It Fl "U" Ns Ar "name"
96: Undefine the symbol
97: .Ar name .
1.7 espie 98: .It Fl I Ar "dirname"
1.15 aaron 99: Add directory
1.7 espie 100: .Ar dirname
101: to the include path.
1.23 espie 102: .It Fl d Ar "flags"
103: Set trace flags.
104: .Ar flags
105: may hold the following:
106: .Bl -tag -width Ds
107: .It Ar a
108: print macro arguments.
109: .It Ar c
110: print macro expansion over several lines.
111: .It Ar e
112: print result of macro expansion.
113: .It Ar f
114: print filename location.
115: .It Ar l
116: print line number.
117: .It Ar q
118: quote arguments and expansion with the current quotes.
119: .It Ar t
120: start with all macros traced.
121: .It Ar x
122: number macro expansions.
123: .It Ar V
124: turn on all options.
125: .El
126: .Pp
127: By default, trace is set to
128: .Qq eq .
1.28 espie 129: .It Fl o Ar filename
130: Send trace output to
131: .Ar filename .
1.23 espie 132: .It Fl t Ar macro
133: Turn tracing on for
134: .Ar macro .
1.12 espie 135: .It Fl g
1.13 aaron 136: Activate GNU-m4 compatibility mode.
1.15 aaron 137: In this mode, changequote with
1.12 espie 138: two empty parameters deactivates quotes, translit handles simple character
1.19 espie 139: ranges (e.g., a-z), regular expressions mimic emacs behavior,
140: and the number of diversions is unlimited.
1.25 espie 141: .It Fl s
142: Output line synchronization directives, suitable for
143: .Xr cpp 1 .
1.17 aaron 144: .El
1.1 deraadt 145: .Sh SYNTAX
146: .Nm m4
1.10 aaron 147: provides the following built-in macros.
148: They may be redefined, losing their original meaning.
149: Return values are null unless otherwise stated.
1.1 deraadt 150: .Bl -tag -width changequotexxx
1.11 espie 151: .It Ic builtin
152: Calls a built-in by its name, overriding possible redefinitions.
1.5 aaron 153: .It Ic changecom
1.10 aaron 154: Change the start and end comment sequences.
155: The default is the pound sign
156: .Pq Ql #
157: and the newline character.
158: With no arguments comments are turned off.
159: The maximum length for a comment marker is five characters.
1.5 aaron 160: .It Ic changequote
1.1 deraadt 161: Defines the quote symbols to be the first and second arguments.
1.10 aaron 162: The symbols may be up to five characters long.
163: If no arguments are
1.1 deraadt 164: given it restores the default open and close single quotes.
1.5 aaron 165: .It Ic decr
1.10 aaron 166: Decrements the argument by 1.
167: The argument must be a valid numeric string.
1.5 aaron 168: .It Ic define
1.1 deraadt 169: Define a new macro named by the first argument to have the
1.10 aaron 170: value of the second argument.
171: Each occurrence of
172: .Ql $n
173: (where
174: .Ar n
175: is 0 through 9) is replaced by the
176: .Ar n Ns 'th
177: argument.
178: .Ql $0
179: is the name of the calling macro.
180: Undefined arguments are replaced by a null string.
181: .Ql $#
182: is replaced by the number of arguments;
183: .Ql $*
184: is replaced by all arguments comma separated;
185: .Ql $@
186: is the same as
187: .Ql $*
188: but all arguments are quoted against further expansion.
1.5 aaron 189: .It Ic defn
1.10 aaron 190: Returns the quoted definition for each argument.
191: This can be used to rename
1.1 deraadt 192: macro definitions (even for built-in macros).
1.5 aaron 193: .It Ic divert
1.1 deraadt 194: There are 10 output queues (numbered 0-9).
195: At the end of processing
196: .Nm m4
197: concatenates all the queues in numerical order to produce the
1.10 aaron 198: final output.
199: Initially the output queue is 0.
200: The divert
1.1 deraadt 201: macro allows you to select a new output queue (an invalid argument
202: passed to divert causes output to be discarded).
1.5 aaron 203: .It Ic divnum
1.1 deraadt 204: Returns the current output queue number.
1.5 aaron 205: .It Ic dnl
1.1 deraadt 206: Discard input characters up to and including the next newline.
1.5 aaron 207: .It Ic dumpdef
1.1 deraadt 208: Prints the names and definitions for the named items, or for everything
209: if no arguments are passed.
1.5 aaron 210: .It Ic errprint
1.1 deraadt 211: Prints the first argument on the standard error output stream.
1.18 espie 212: .It Ic esyscmd
1.26 pvalchev 213: Passes its first argument to a shell and returns the shell's standard output.
1.18 espie 214: Note that the shell shares its standard input and standard error with
215: .Nm
1.5 aaron 216: .It Ic eval
1.1 deraadt 217: Computes the first argument as an arithmetic expression using 32-bit
1.10 aaron 218: arithmetic.
219: Operators are the standard C ternary, arithmetic, logical,
220: shift, relational, bitwise, and parentheses operators.
221: You can specify
222: octal, decimal, and hexadecimal numbers as in C.
223: The second argument (if any)
224: specifies the radix for the result and the third argument (if any)
225: specifies the minimum number of digits in the result.
1.5 aaron 226: .It Ic expr
227: This is an alias for
228: .Ic eval .
229: .It Ic ifdef
1.1 deraadt 230: If the macro named by the first argument is defined then return the second
1.10 aaron 231: argument, otherwise the third.
232: If there is no third argument, the value is
233: .Dv NULL .
234: The word
235: .Qq unix
236: is predefined.
1.5 aaron 237: .It Ic ifelse
238: If the first argument matches the second argument then
239: .Ic ifelse
240: returns
1.10 aaron 241: the third argument.
242: If the match fails the three arguments are
1.1 deraadt 243: discarded and the next three arguments are used until there is
1.10 aaron 244: zero or one arguments left, either this last argument or
245: .Dv NULL
246: is returned if no other matches were found.
1.5 aaron 247: .It Ic include
1.1 deraadt 248: Returns the contents of the file specified in the first argument.
1.7 espie 249: If the file is not found as is, look through the include path:
250: first the directories specified with
251: .Fl I
252: on the command line, then the environment variable
1.10 aaron 253: .Ev M4PATH ,
1.7 espie 254: as a colon-separated list of directories.
1.1 deraadt 255: Include aborts with an error message if the file cannot be included.
1.5 aaron 256: .It Ic incr
1.10 aaron 257: Increments the argument by 1.
258: The argument must be a valid numeric string.
1.5 aaron 259: .It Ic index
1.1 deraadt 260: Returns the index of the second argument in the first argument (e.g.,
1.10 aaron 261: .Ic index(the quick brown fox jumped, fox)
262: returns 16).
263: If the second
264: argument is not found index returns \-1.
1.11 espie 265: .It Ic indir
1.26 pvalchev 266: Indirectly calls the macro whose name is passed as the first argument,
1.11 espie 267: with the remaining arguments passed as first, ... arguments.
1.5 aaron 268: .It Ic len
1.10 aaron 269: Returns the number of characters in the first argument.
270: Extra arguments
1.1 deraadt 271: are ignored.
1.5 aaron 272: .It Ic m4exit
1.1 deraadt 273: Immediately exits with the return value specified by the first argument,
274: 0 if none.
1.5 aaron 275: .It Ic m4wrap
1.10 aaron 276: Allows you to define what happens at the final
277: .Dv EOF ,
278: usually for cleanup purposes (e.g.,
279: .Ic m4wrap("cleanup(tempfile)")
280: causes the macro cleanup to be
1.16 aaron 281: invoked after all other processing is done).
1.5 aaron 282: .It Ic maketemp
1.10 aaron 283: Translates the string
1.15 aaron 284: .Dq XXXXX
1.10 aaron 285: in the first argument with the current process
286: ID leaving other characters alone.
287: This can be used to create unique
1.1 deraadt 288: temporary file names.
1.5 aaron 289: .It Ic paste
1.1 deraadt 290: Includes the contents of the file specified by the first argument without
1.10 aaron 291: any macro processing.
292: Aborts with an error message if the file cannot be
1.1 deraadt 293: included.
1.11 espie 294: .It Ic patsubst
295: Substitutes a regular expression in a string with a replacement string.
296: Usual substitution patterns apply: an ampersand
1.15 aaron 297: .Pq Ql &
1.11 espie 298: is replaced by the string matching the regular expression.
299: The string
300: .Ql \e# ,
301: where
302: .Ql #
303: is a digit, is replaced by the corresponding back-reference.
1.5 aaron 304: .It Ic popdef
305: Restores the
306: .Ic pushdef Ns ed
307: definition for each argument.
308: .It Ic pushdef
309: Takes the same arguments as
310: .Ic define ,
311: but it saves the definition on a
312: stack for later retrieval by
313: .Ic popdef .
1.11 espie 314: .It Ic regexp
1.13 aaron 315: Finds a regular expression in a string.
316: If no further arguments are given,
1.14 aaron 317: it returns the first match position or \-1 if no match.
318: If a third argument
1.11 espie 319: is provided, it returns the replacement string, with sub-patterns replaced.
1.5 aaron 320: .It Ic shift
1.1 deraadt 321: Returns all but the first argument, the remaining arguments are
1.10 aaron 322: quoted and pushed back with commas in between.
323: The quoting
1.1 deraadt 324: nullifies the effect of the extra scan that will subsequently be
325: performed.
1.5 aaron 326: .It Ic sinclude
327: Similar to
328: .Ic include ,
329: except it ignores any errors.
330: .It Ic spaste
331: Similar to
332: .Ic paste ,
333: except it ignores any errors.
334: .It Ic substr
1.1 deraadt 335: Returns a substring of the first argument starting at the offset specified
336: by the second argument and the length specified by the third argument.
337: If no third argument is present it returns the rest of the string.
1.5 aaron 338: .It Ic syscmd
1.10 aaron 339: Passes the first argument to the shell.
340: Nothing is returned.
1.5 aaron 341: .It Ic sysval
342: Returns the return value from the last
343: .Ic syscmd .
1.22 espie 344: .It Ic traceon
345: Enables tracing of macro expansions for the given arguments, or for all
346: macros if no argument is given.
347: .It Ic traceoff
348: Disables tracing of macro expansions for the given arguments, or for all
349: macros if no argument is given.
1.5 aaron 350: .It Ic translit
1.1 deraadt 351: Transliterate the characters in the first argument from the set
1.10 aaron 352: given by the second argument to the set given by the third.
1.21 aaron 353: You cannot use
1.1 deraadt 354: .Xr tr 1
355: style abbreviations.
1.5 aaron 356: .It Ic undefine
1.24 espie 357: Removes the definition for the macros specified by its arguments.
1.5 aaron 358: .It Ic undivert
1.1 deraadt 359: Flushes the named output queues (or all queues if no arguments).
1.5 aaron 360: .It Ic unix
1.1 deraadt 361: A pre-defined macro for testing the OS platform.
1.11 espie 362: .It Ic __line__
363: Returns the current file's line number.
364: .It Ic __file__
365: Returns the current file's name.
1.1 deraadt 366: .El
1.23 espie 367: .Sh COMPATIBILITY
368: .Nm
369: follows the Single Unix 2 specification, along with a few extensions taken
370: from
371: .Nm gnu-m4 .
372: .Pp
373: The
374: .Fl s
375: option
376: .Po
377: .Xr cpp 1 's
378: #line directives
379: .Pc
380: is currently not supported.
381: Flags
382: .Fl I ,
383: .Fl d ,
384: .Fl t
385: are non-standard.
386: .Pp
387: The output format of tracing and of
388: .Ic dumpdef
389: are not specified in any standard,
390: are likely to change and should not be relied upon.
391: The current format of tracing is closely modelled on
392: .Nm gnu-m4 ,
393: to allow
394: .Nm autoconf
395: to work.
396: .Pp
397: For portability, one should not use the macros
398: .Ic builtin ,
399: .Ic esycmd ,
400: .Ic expr ,
401: .Ic indir ,
402: .Ic paste ,
403: .Ic patsubst ,
404: .Ic regexp ,
405: .Ic spaste ,
406: .Ic unix ,
407: .Ic __line__ ,
408: .Ic __file__ .
409: .Pp
1.30 jmc 410: All built-ins do expand without arguments in many other
1.23 espie 411: .Nm m4 .
412: .Pp
413: Many other
414: .Nm
415: have dire size limitations with respect to buffer sizes.
1.21 aaron 416: .Sh AUTHORS
1.11 espie 417: Ozan Yigit <oz@sis.yorku.ca> and Richard A. O'Keefe (ok@goanna.cs.rmit.OZ.AU).
418: GNU-m4 compatibility extensions by Marc Espie <espie@cvs.openbsd.org>.
![[BACK]](/icons/back.gif){kind=icon}
Return to m4.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / m4