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