usr.bin/m4/m4.1

   1 .\"     $NetBSD: m4.1,v 1.23 2012/04/08 22:00:39 wiz Exp $
   2 .\"     @(#) $OpenBSD: m4.1,v 1.64 2017/06/15 13:48:42 bcallah Exp $
   3 .\"
   4 .\" Copyright (c) 1989, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" This code is derived from software contributed to Berkeley by
   8 .\" Ozan Yigit at York University.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd June 21, 2023
  35 .Dt M4 1
  36 .Os
  37 .Sh NAME
  38 .Nm m4
  39 .Nd macro language processor
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl EGgPs
  43 .Oo
  44 .Sm off
  45 .Fl D Ar name Op No = Ar value
  46 .Sm on
  47 .Oc
  48 .Op Fl d Oo Oo +- Oc Ns Ar flags Oc
  49 .Op Fl I Ar dirname
  50 .Op Fl o Ar filename
  51 .Op Fl t Ar macro
  52 .Op Fl U Ns Ar name
  53 .Op Ar
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  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 If no input files are given,
  60 .Nm
  61 reads from the standard input,
  62 otherwise files specified on the command line are
  63 processed in the given order.
  64 Input files can be regular files, files in the m4 include paths, or a
  65 single dash
  66 .Pq Sq - ,
  67 denoting standard input.
  68 .Nm
  69 writes
  70 the processed text to the standard output, unless told otherwise.
  71 .Pp
  72 Macro calls have the form name(argument1[, argument2, ..., argumentN]).
  73 .Pp
  74 There cannot be any space following the macro name and the open
  75 parenthesis
  76 .Pq Sq \&( .
  77 If the macro name is not followed by an open
  78 parenthesis it is processed with no arguments.
  79 .Pp
  80 Macro names consist of a leading alphabetic or underscore
  81 possibly followed by alphanumeric or underscore characters, e.g.,
  82 valid macro names match the pattern
  83 .Dq [a-zA-Z_][a-zA-Z0-9_]* .
  84 .Pp
  85 In arguments to macros, leading unquoted space, tab, and newline
  86 .Pq Sq \en
  87 characters are ignored.
  88 To quote strings, use left and right single quotes
  89 .Pq e.g., Sq \ \&this is a string with a leading space .
  90 You can change the quote characters with the
  91 .Ic changequote
  92 built-in macro.
  93 .Pp
  94 Most built-ins do not make any sense without arguments, and hence are not
  95 recognized as special when not followed by an open parenthesis.
  96 .Pp
  97 The options are as follows:
  98 .Bl -tag -width Ds
  99 .It Fl D Ns Ar name Ns Oo = Ns Ar value Oc , Fl -define Ns = Ns Ar name Ns Oo = Ns Ar value Oc
 100 Define the symbol
 101 .Ar name
 102 to have some value (or
 103 .Dv NULL ) .
 104 .It Fl d Oo Oo +|- Oc Ns Ar flags Oc , Fl -debug Ns = Ns Oo Oo +|- Oc Ns Ar flags Oc
 105 Set or unset trace flags.
 106 The trace flags are as follows:
 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
 128 If
 129 .Qq +
 130 or
 131 .Qq -
 132 is used, the specified flags are added to or removed from the set of
 133 active trace flags, respectively; otherwise, the specified flags
 134 replace the set of active trace flags.
 135 .Pp
 136 Specifying this option without an argument is equivalent to specifying
 137 it with the argument
 138 .Qq aeq .
 139 .Pp
 140 By default, trace is set to
 141 .Qq eq .
 142 .It Fl E , Fl -fatal-warnings
 143 Set warnings to be fatal.
 144 When a single
 145 .Fl E
 146 flag is specified, if warnings are issued, execution
 147 continues but
 148 .Nm
 149 will exit with a non-zero exit status.
 150 When multiple
 151 .Fl E
 152 flags are specified, execution will halt upon issuing the
 153 first warning and
 154 .Nm
 155 will exit with a non-zero exit status.
 156 This behavior matches GNU m4 1.4.9 and later.
 157 .It Fl G , Fl -traditional
 158 Disable GNU compatibility mode (see
 159 .Fl g
 160 below).
 161 .It Fl g , Fl -gnu
 162 Enable GNU compatibility mode.
 163 In this mode,
 164 .Ic translit
 165 handles simple character ranges (e.g.,
 166 .Sq a-z ) ,
 167 regular expressions mimic Emacs behavior,
 168 multiple
 169 .Ic m4wrap
 170 calls are handled as a stack,
 171 the number of diversions is unlimited,
 172 empty names for macro definitions are allowed,
 173 .Ic undivert
 174 can be used to include files,
 175 and
 176 .Ic eval
 177 understands
 178 .Sq 0rbase:value
 179 numbers.
 180 .It Fl I Ar dirname , Fl -include Ns = Ns Ar dirname
 181 Add directory
 182 .Ar dirname
 183 to the include path.
 184 .It Fl o Ar filename , Fl -error-output Ns = Ns Ar filename
 185 Send trace output to
 186 .Ar filename .
 187 .It Fl P , Fl -prefix-builtins
 188 Prefix all built-in macros with
 189 .Sq m4_ .
 190 For example, instead of writing
 191 .Ic define ,
 192 use
 193 .Ic m4_define .
 194 .It Fl s , Fl -synclines
 195 Output line synchronization directives, suitable for
 196 .Xr cpp 1 .
 197 .It Fl t Ar macro , Fl -trace Ns = Ns Ar macro
 198 Turn tracing on for
 199 .Ar macro .
 200 .It Fl U Ns Ar name , Fl -undefine Ns = Ns Ar name
 201 Undefine the symbol
 202 .Ar name .
 203 .El
 204 .Sh SYNTAX
 205 .Nm
 206 provides the following built-in macros.
 207 They may be redefined, losing their original meaning.
 208 Return values are null unless otherwise stated.
 209 .Bl -tag -width changequote
 210 .It Fn builtin name
 211 Calls a built-in by its
 212 .Fa name ,
 213 overriding possible redefinitions.
 214 .It Fn changecom startcomment endcomment
 215 Changes the start comment and end comment sequences.
 216 Comment sequences may be up to five characters long.
 217 The default values are the hash sign
 218 and the newline character.
 219 .Bd -literal -offset indent
 220 # This is a comment
 221 .Ed
 222 .Pp
 223 With no arguments, comments are turned off.
 224 With one single argument, the end comment sequence is set
 225 to the newline character.
 226 .It Fn changequote beginquote endquote
 227 Defines the open quote and close quote sequences.
 228 Quote sequences may be up to five characters long.
 229 The default values are the backquote character and the quote
 230 character.
 231 .Bd -literal -offset indent
 232 `Here is a quoted string'
 233 .Ed
 234 .Pp
 235 With no arguments, the default quotes are restored.
 236 With one single argument, the close quote sequence is set
 237 to the newline character.
 238 .It Fn decr arg
 239 Decrements the argument
 240 .Fa arg
 241 by 1.
 242 The argument
 243 .Fa arg
 244 must be a valid numeric string.
 245 .It Fn define name value
 246 Define a new macro named by the first argument
 247 .Fa name
 248 to have the
 249 value of the second argument
 250 .Fa value .
 251 Each occurrence of
 252 .Sq $n
 253 (where
 254 .Ar n
 255 is 0 through 9) is replaced by the
 256 .Ar n Ns 'th
 257 argument.
 258 .Sq $0
 259 is the name of the calling macro.
 260 Undefined arguments are replaced by a null string.
 261 .Sq $#
 262 is replaced by the number of arguments;
 263 .Sq $*
 264 is replaced by all arguments comma separated;
 265 .Sq $@
 266 is the same as
 267 .Sq $*
 268 but all arguments are quoted against further expansion.
 269 .It Fn defn name ...
 270 Returns the quoted definition for each argument.
 271 This can be used to rename
 272 macro definitions (even for built-in macros).
 273 .It Fn divert num
 274 There are 10 output queues (numbered 0-9).
 275 At the end of processing
 276 .Nm
 277 concatenates all the queues in numerical order to produce the
 278 final output.
 279 Initially the output queue is 0.
 280 The divert
 281 macro allows you to select a new output queue (an invalid argument
 282 passed to divert causes output to be discarded).
 283 .It Ic divnum
 284 Returns the current output queue number.
 285 .It Ic dnl
 286 Discard input characters up to and including the next newline.
 287 .It Fn dumpdef name ...
 288 Prints the names and definitions for the named items, or for everything
 289 if no arguments are passed.
 290 .It Fn errprint msg
 291 Prints the first argument on the standard error output stream.
 292 .It Fn esyscmd cmd
 293 Passes its first argument to a shell and returns the shell's standard output.
 294 Note that the shell shares its standard input and standard error with
 295 .Nm .
 296 .It Fn eval expr[,radix[,minimum]]
 297 Computes the first argument as an arithmetic expression using 32-bit
 298 arithmetic.
 299 Operators are the standard C ternary, arithmetic, logical,
 300 shift, relational, bitwise, and parentheses operators.
 301 You can specify
 302 octal, decimal, and hexadecimal numbers as in C.
 303 The optional second argument
 304 .Fa radix
 305 specifies the radix for the result and the optional third argument
 306 .Fa minimum
 307 specifies the minimum number of digits in the result.
 308 .It Fn expr expr
 309 This is an alias for
 310 .Ic eval .
 311 .It Fn format formatstring arg1 ...
 312 Returns
 313 .Fa formatstring
 314 with escape sequences substituted with
 315 .Fa arg1
 316 and following arguments, in a way similar to
 317 .Xr printf 3 .
 318 This built-in is only available in GNU-m4 compatibility mode, and the only
 319 parameters implemented are there for autoconf compatibility:
 320 left-padding flag, an optional field width, a maximum field width,
 321 *-specified field widths, and the %s and %c data type.
 322 .It Fn ifdef name yes no
 323 If the macro named by the first argument is defined then return the second
 324 argument, otherwise the third.
 325 If there is no third argument, the value is
 326 .Dv NULL .
 327 The word
 328 .Qq unix
 329 is predefined.
 330 .It Fn ifelse a b yes ...
 331 If the first argument
 332 .Fa a
 333 matches the second argument
 334 .Fa b
 335 then
 336 .Fn ifelse
 337 returns
 338 the third argument
 339 .Fa yes .
 340 If the match fails the three arguments are
 341 discarded and the next three arguments are used until there is
 342 zero or one arguments left, either this last argument or
 343 .Dv NULL
 344 is returned if no other matches were found.
 345 .It Fn include name
 346 Returns the contents of the file specified in the first argument.
 347 If the file is not found as is, look through the include path:
 348 first the directories specified with
 349 .Fl I
 350 on the command line, then the environment variable
 351 .Ev M4PATH ,
 352 as a colon-separated list of directories.
 353 Include aborts with an error message if the file cannot be included.
 354 .It Fn incr arg
 355 Increments the argument by 1.
 356 The argument must be a valid numeric string.
 357 .It Fn index string substring
 358 Returns the index of the second argument in the first argument (e.g.,
 359 .Ic index(the quick brown fox jumped, fox)
 360 returns 16).
 361 If the second
 362 argument is not found index returns \-1.
 363 .It Fn indir macro arg1 ...
 364 Indirectly calls the macro whose name is passed as the first argument,
 365 with the remaining arguments passed as first, ... arguments.
 366 .It Fn len arg
 367 Returns the number of characters in the first argument.
 368 Extra arguments
 369 are ignored.
 370 .It Fn m4exit code
 371 Immediately exits with the return value specified by the first argument,
 372 0 if none.
 373 .It Fn m4wrap todo
 374 Allows you to define what happens at the final
 375 .Dv EOF ,
 376 usually for cleanup purposes (e.g.,
 377 .Ic m4wrap("cleanup(tempfile)")
 378 causes the macro cleanup to be
 379 invoked after all other processing is done).
 380 .Pp
 381 Multiple calls to
 382 .Fn m4wrap
 383 get inserted in sequence at the final
 384 .Dv EOF .
 385 .It Fn maketemp template
 386 Like
 387 .Ic mkstemp .
 388 .It Fn mkstemp template
 389 Invokes
 390 .Xr mkstemp 3
 391 on the first argument, and returns the modified string.
 392 This can be used to create unique
 393 temporary file names.
 394 .It Fn paste file
 395 Includes the contents of the file specified by the first argument without
 396 any macro processing.
 397 Aborts with an error message if the file cannot be
 398 included.
 399 .It Fn patsubst string regexp replacement
 400 Substitutes a regular expression in a string with a replacement string.
 401 Usual substitution patterns apply: an ampersand
 402 .Pq Sq \&&
 403 is replaced by the string matching the regular expression.
 404 The string
 405 .Sq \e# ,
 406 where
 407 .Sq #
 408 is a digit, is replaced by the corresponding back-reference.
 409 .It Fn popdef arg ...
 410 Restores the
 411 .Ic pushdef Ns ed
 412 definition for each argument.
 413 .It Fn pushdef macro def
 414 Takes the same arguments as
 415 .Ic define ,
 416 but it saves the definition on a
 417 stack for later retrieval by
 418 .Fn popdef .
 419 .It Fn regexp string regexp replacement
 420 Finds a regular expression in a string.
 421 If no further arguments are given,
 422 it returns the first match position or \-1 if no match.
 423 If a third argument
 424 is provided, it returns the replacement string, with sub-patterns replaced.
 425 .It Fn shift arg1 ...
 426 Returns all but the first argument, the remaining arguments are
 427 quoted and pushed back with commas in between.
 428 The quoting
 429 nullifies the effect of the extra scan that will subsequently be
 430 performed.
 431 .It Fn sinclude file
 432 Similar to
 433 .Ic include ,
 434 except it ignores any errors.
 435 .It Fn spaste file
 436 Similar to
 437 .Fn paste ,
 438 except it ignores any errors.
 439 .It Fn substr string offset length
 440 Returns a substring of the first argument starting at the offset specified
 441 by the second argument and the length specified by the third argument.
 442 If no third argument is present it returns the rest of the string.
 443 .It Fn syscmd cmd
 444 Passes the first argument to the shell.
 445 Nothing is returned.
 446 .It Ic sysval
 447 Returns the return value from the last
 448 .Ic syscmd .
 449 .It Fn traceon arg ...
 450 Enables tracing of macro expansions for the given arguments, or for all
 451 macros if no argument is given.
 452 .It Fn traceoff arg ...
 453 Disables tracing of macro expansions for the given arguments, or for all
 454 macros if no argument is given.
 455 .It Fn translit string mapfrom mapto
 456 Transliterate the characters in the first argument from the set
 457 given by the second argument to the set given by the third.
 458 You cannot use
 459 .Xr tr 1
 460 style abbreviations.
 461 .It Fn undefine name1 ...
 462 Removes the definition for the macros specified by its arguments.
 463 .It Fn undivert arg ...
 464 Flushes the named output queues (or all queues if no arguments).
 465 .It Ic unix
 466 A pre-defined macro for testing the OS platform.
 467 .It Ic __line__
 468 Returns the current file's line number.
 469 .It Ic __file__
 470 Returns the current file's name.
 471 .El
 472 .Sh EXIT STATUS
 473 .Ex -std m4
 474 .Pp
 475 But note that the
 476 .Ic m4exit
 477 macro can modify the exit status, as can the
 478 .Fl E
 479 flag.
 480 .Sh SEE ALSO
 481 .Rs
 482 .\" 4.4BSD PSD:17
 483 .%A B. W. Kernighan
 484 .%A D. M. Ritchie
 485 .%I AT&T Bell Laboratories
 486 .%T The M4 Macro Processor
 487 .%R Computing Science Technical Report
 488 .%N 59
 489 .%D July 1977
 490 .Re
 491 .Sh STANDARDS
 492 The
 493 .Nm
 494 utility is compliant with the
 495 .St -p1003.1-2008
 496 specification.
 497 .Pp
 498 The flags
 499 .Op Fl dEGgIPot
 500 and the macros
 501 .Ic builtin ,
 502 .Ic esyscmd ,
 503 .Ic expr ,
 504 .Ic format ,
 505 .Ic indir ,
 506 .Ic paste ,
 507 .Ic patsubst ,
 508 .Ic regexp ,
 509 .Ic spaste ,
 510 .Ic unix ,
 511 .Ic __line__ ,
 512 and
 513 .Ic __file__
 514 are extensions to that specification.
 515 .Pp
 516 .Ic maketemp
 517 is not supposed to be a synonym for
 518 .Ic mkstemp ,
 519 but instead to be an insecure temporary file name creation function.
 520 It is marked by
 521 .St -p1003.1-2008
 522 as being obsolescent and should not be used if portability is a concern.
 523 .Pp
 524 The output format of
 525 .Ic traceon
 526 and
 527 .Ic dumpdef
 528 are not specified in any standard,
 529 are likely to change and should not be relied upon.
 530 The current format of tracing is closely modelled on
 531 .Nm gnu-m4 ,
 532 to allow
 533 .Nm autoconf
 534 to work.
 535 .Pp
 536 The built-ins
 537 .Ic pushdef
 538 and
 539 .Ic popdef
 540 handle macro definitions as a stack.
 541 However,
 542 .Ic define
 543 interacts with the stack in an undefined way.
 544 In this implementation,
 545 .Ic define
 546 replaces the top-most definition only.
 547 Other implementations may erase all definitions on the stack instead.
 548 .Pp
 549 All built-ins do expand without arguments in many other
 550 .Nm .
 551 .Pp
 552 Many other
 553 .Nm
 554 have dire size limitations with respect to buffer sizes.
 555 .Sh AUTHORS
 556 .An -nosplit
 557 .An Ozan Yigit Aq Mt oz@sis.yorku.ca
 558 and
 559 .An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU .
 560 .Pp
 561 GNU-m4 compatibility extensions by
 562 .An Marc Espie Aq Mt espie@cvs.openbsd.org .