usr.bin/m4/m4.1

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