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