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