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