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