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