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