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