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