usr.bin/m4/m4.1

   1 .\"     $NetBSD: m4.1,v 1.22 2010/05/14 17:14:28 joerg Exp $
   2 .\"     @(#) $OpenBSD: m4.1,v 1.56 2009/10/14 17:19:47 sthen 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: src/usr.bin/m4/m4.1,v 1.30 2012/11/17 01:54:24 svnexp Exp $
  35 .\"
  36 .Dd October 14, 2009
  37 .Dt M4 1
  38 .Os
  39 .Sh NAME
  40 .Nm m4
  41 .Nd macro language processor
  42 .Sh SYNOPSIS
  43 .Nm m4
  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 .Bk -words
  54 .Op Fl t Ar macro
  55 .Op Fl U Ns Ar name
  56 .Op Ar
  57 .Ek
  58 .Sh DESCRIPTION
  59 The
  60 .Nm m4
  61 utility is a macro processor that can be used as a front end to any
  62 language (e.g., C, ratfor, fortran, lex, and yacc).
  63 If no input files are given,
  64 .Nm m4
  65 reads from the standard input,
  66 otherwise files specified on the command line are
  67 processed in the given order.
  68 Input files can be regular files, files in the m4 include paths, or a
  69 single dash
  70 .Pq Sq - ,
  71 denoting standard input.
  72 .Nm m4
  73 writes
  74 the processed text to the standard output, unless told otherwise.
  75 .Pp
  76 Macro calls have the form name(argument1[, argument2, ..., argumentN]).
  77 .Pp
  78 There cannot be any space following the macro name and the open
  79 parenthesis
  80 .Sq \&( .
  81 If the macro name is not followed by an open
  82 parenthesis it is processed with no arguments.
  83 .Pp
  84 Macro names consist of a leading alphabetic or underscore
  85 possibly followed by alphanumeric or underscore characters, e.g.,
  86 valid macro names match the pattern
  87 .Dq [a-zA-Z_][a-zA-Z0-9_]* .
  88 .Pp
  89 In arguments to macros, leading unquoted space, tab, and newline
  90 .Pq Sq \en
  91 characters are ignored.
  92 To quote strings, use left and right single quotes
  93 .Po e.g.,\ \&
  94 .Sq "\ this is a string with a leading space"
  95 .Pc .
  96 You can change the quote characters with the
  97 .Ic changequote
  98 built-in macro.
  99 .Pp
 100 Most built-ins do not make any sense without arguments, and hence are not
 101 recognized as special when not followed by an open parenthesis.
 102 .Pp
 103 The options are as follows:
 104 .Bl -tag -width Ds
 105 .It Fl D Ns Ar name Ns Op Pf = Ns Ar value
 106 Define the symbol
 107 .Ar name
 108 to have some value (or
 109 .Dv NULL ) .
 110 .It Fl d Ar "flags"
 111 Set trace flags.
 112 .Ar flags
 113 may hold the following:
 114 .Bl -tag -width Ds
 115 .It Ar a
 116 print macro arguments.
 117 .It Ar c
 118 print macro expansion over several lines.
 119 .It Ar e
 120 print result of macro expansion.
 121 .It Ar f
 122 print filename location.
 123 .It Ar l
 124 print line number.
 125 .It Ar q
 126 quote arguments and expansion with the current quotes.
 127 .It Ar t
 128 start with all macros traced.
 129 .It Ar x
 130 number macro expansions.
 131 .It Ar V
 132 turn on all options.
 133 .El
 134 .Pp
 135 By default, trace is set to
 136 .Qq eq .
 137 .It Fl g
 138 Activate GNU-m4 compatibility mode.
 139 In this mode, translit handles simple character
 140 ranges (e.g., a-z), regular expressions mimic emacs behavior,
 141 multiple m4wrap calls are handled as a stack,
 142 the number of diversions is unlimited,
 143 empty names for macro definitions are allowed,
 144 and eval understands
 145 .Sq 0rbase:value
 146 numbers.
 147 .It Fl I Ar "dirname"
 148 Add directory
 149 .Ar dirname
 150 to the include path.
 151 .It Fl o Ar filename
 152 Send trace output to
 153 .Ar filename .
 154 .It Fl P
 155 Prefix all built-in macros with
 156 .Sq m4_ .
 157 For example, instead of writing
 158 .Ic define ,
 159 use
 160 .Ic m4_define .
 161 .It Fl s
 162 Output line synchronization directives, suitable for
 163 .Xr cpp 1 .
 164 .It Fl t Ar macro
 165 Turn tracing on for
 166 .Ar macro .
 167 .It Fl "U" Ns Ar "name"
 168 Undefine the symbol
 169 .Ar name .
 170 .El
 171 .Sh SYNTAX
 172 .Nm m4
 173 provides the following built-in macros.
 174 They may be redefined, losing their original meaning.
 175 Return values are null unless otherwise stated.
 176 .Bl -tag -width changequote
 177 .It Fn builtin name
 178 Calls a built-in by its
 179 .Fa name ,
 180 overriding possible redefinitions.
 181 .It Fn changecom startcomment endcomment
 182 Changes the start comment and end comment sequences.
 183 Comment sequences may be up to five characters long.
 184 The default values are the hash sign
 185 and the newline character.
 186 .Bd -literal -offset indent
 187 # This is a comment
 188 .Ed
 189 .Pp
 190 With no arguments, comments are turned off.
 191 With one single argument, the end comment sequence is set
 192 to the newline character.
 193 .It Fn changequote beginquote endquote
 194 Defines the open quote and close quote sequences.
 195 Quote sequences may be up to five characters long.
 196 The default values are the backquote character and the quote
 197 character.
 198 .Bd -literal -offset indent
 199 `Here is a quoted string'
 200 .Ed
 201 .Pp
 202 With no arguments, the default quotes are restored.
 203 With one single argument, the close quote sequence is set
 204 to the newline character.
 205 .It Fn decr arg
 206 Decrements the argument
 207 .Fa arg
 208 by 1.
 209 The argument
 210 .Fa arg
 211 must be a valid numeric string.
 212 .It Fn define name value
 213 Define a new macro named by the first argument
 214 .Fa name
 215 to have the
 216 value of the second argument
 217 .Fa value .
 218 Each occurrence of
 219 .Sq $n
 220 (where
 221 .Ar n
 222 is 0 through 9) is replaced by the
 223 .Ar n Ns 'th
 224 argument.
 225 .Sq $0
 226 is the name of the calling macro.
 227 Undefined arguments are replaced by a null string.
 228 .Sq $#
 229 is replaced by the number of arguments;
 230 .Sq $*
 231 is replaced by all arguments comma separated;
 232 .Sq $@
 233 is the same as
 234 .Sq $*
 235 but all arguments are quoted against further expansion.
 236 .It Fn defn name ...
 237 Returns the quoted definition for each argument.
 238 This can be used to rename
 239 macro definitions (even for built-in macros).
 240 .It Fn divert num
 241 There are 10 output queues (numbered 0-9).
 242 At the end of processing
 243 .Nm m4
 244 concatenates all the queues in numerical order to produce the
 245 final output.
 246 Initially the output queue is 0.
 247 The divert
 248 macro allows you to select a new output queue (an invalid argument
 249 passed to divert causes output to be discarded).
 250 .It Ic divnum
 251 Returns the current output queue number.
 252 .It Ic dnl
 253 Discard input characters up to and including the next newline.
 254 .It Fn dumpdef name ...
 255 Prints the names and definitions for the named items, or for everything
 256 if no arguments are passed.
 257 .It Fn errprint msg
 258 Prints the first argument on the standard error output stream.
 259 .It Fn esyscmd cmd
 260 Passes its first argument to a shell and returns the shell's standard output.
 261 Note that the shell shares its standard input and standard error with
 262 .Nm m4 .
 263 .It Fn eval expr
 264 Computes the first argument as an arithmetic expression using 32-bit
 265 arithmetic.
 266 Operators are the standard C ternary, arithmetic, logical,
 267 shift, relational, bitwise, and parentheses operators.
 268 You can specify
 269 octal, decimal, and hexadecimal numbers as in C.
 270 The second argument (if any)
 271 specifies the radix for the result and the third argument (if any)
 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 Invokes
 352 .Xr mkstemp 3
 353 on the first argument, and returns the modified string.
 354 This can be used to create unique
 355 temporary file names.
 356 .It Fn paste file
 357 Includes the contents of the file specified by the first argument without
 358 any macro processing.
 359 Aborts with an error message if the file cannot be
 360 included.
 361 .It Fn patsubst string regexp replacement
 362 Substitutes a regular expression in a string with a replacement string.
 363 Usual substitution patterns apply: an ampersand
 364 .Pq Sq \&&
 365 is replaced by the string matching the regular expression.
 366 The string
 367 .Sq \e# ,
 368 where
 369 .Sq #
 370 is a digit, is replaced by the corresponding back-reference.
 371 .It Fn popdef arg ...
 372 Restores the
 373 .Ic pushdef Ns ed
 374 definition for each argument.
 375 .It Fn pushdef macro def
 376 Takes the same arguments as
 377 .Ic define ,
 378 but it saves the definition on a
 379 stack for later retrieval by
 380 .Fn popdef .
 381 .It Fn regexp string regexp replacement
 382 Finds a regular expression in a string.
 383 If no further arguments are given,
 384 it returns the first match position or \-1 if no match.
 385 If a third argument
 386 is provided, it returns the replacement string, with sub-patterns replaced.
 387 .It Fn shift arg1 ...
 388 Returns all but the first argument, the remaining arguments are
 389 quoted and pushed back with commas in between.
 390 The quoting
 391 nullifies the effect of the extra scan that will subsequently be
 392 performed.
 393 .It Fn sinclude file
 394 Similar to
 395 .Ic include ,
 396 except it ignores any errors.
 397 .It Fn spaste file
 398 Similar to
 399 .Fn paste ,
 400 except it ignores any errors.
 401 .It Fn substr string offset length
 402 Returns a substring of the first argument starting at the offset specified
 403 by the second argument and the length specified by the third argument.
 404 If no third argument is present it returns the rest of the string.
 405 .It Fn syscmd cmd
 406 Passes the first argument to the shell.
 407 Nothing is returned.
 408 .It Ic sysval
 409 Returns the return value from the last
 410 .Ic syscmd .
 411 .It Fn traceon arg ...
 412 Enables tracing of macro expansions for the given arguments, or for all
 413 macros if no argument is given.
 414 .It Fn traceoff arg ...
 415 Disables tracing of macro expansions for the given arguments, or for all
 416 macros if no argument is given.
 417 .It Fn translit string mapfrom mapto
 418 Transliterate the characters in the first argument from the set
 419 given by the second argument to the set given by the third.
 420 You cannot use
 421 .Xr tr 1
 422 style abbreviations.
 423 .It Fn undefine name1 ...
 424 Removes the definition for the macros specified by its arguments.
 425 .It Fn undivert arg ...
 426 Flushes the named output queues (or all queues if no arguments).
 427 .It Ic unix
 428 A pre-defined macro for testing the OS platform.
 429 .It Ic __line__
 430 Returns the current file's line number.
 431 .It Ic __file__
 432 Returns the current file's name.
 433 .El
 434 .Sh STANDARDS
 435 The
 436 .Nm
 437 utility is compliant with the
 438 .St -p1003.1-2008
 439 specification.
 440 .Pp
 441 The flags
 442 .Op Fl dgIot
 443 and the macros
 444 .Ic builtin ,
 445 .Ic esyscmd ,
 446 .Ic expr ,
 447 .Ic format ,
 448 .Ic indir ,
 449 .Ic paste ,
 450 .Ic patsubst ,
 451 .Ic regexp ,
 452 .Ic spaste ,
 453 .Ic unix ,
 454 .Ic __line__ ,
 455 and
 456 .Ic __file__
 457 are extensions to that specification.
 458 .Pp
 459 The output format of tracing and of
 460 .Ic dumpdef
 461 are not specified in any standard,
 462 are likely to change and should not be relied upon.
 463 The current format of tracing is closely modelled on
 464 .Nm gnu-m4 ,
 465 to allow
 466 .Nm autoconf
 467 to work.
 468 .Pp
 469 The built-ins
 470 .Ic pushdef
 471 and
 472 .Ic popdef
 473 handle macro definitions as a stack.
 474 However,
 475 .Ic define
 476 interacts with the stack in an undefined way.
 477 In this implementation,
 478 .Ic define
 479 replaces the top-most definition only.
 480 Other implementations may erase all definitions on the stack instead.
 481 .Pp
 482 All built-ins do expand without arguments in many other
 483 .Nm m4 .
 484 .Pp
 485 Many other
 486 .Nm
 487 have dire size limitations with respect to buffer sizes.
 488 .Sh AUTHORS
 489 .An -nosplit
 490 .An Ozan Yigit Aq oz@sis.yorku.ca
 491 and
 492 .An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU .
 493 .Pp
 494 GNU-m4 compatibility extensions by
 495 .An Marc Espie Aq espie@cvs.openbsd.org .