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