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