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