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