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