1.\" $NetBSD: m4.1,v 1.23 2012/04/08 22:00:39 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 October 14, 2009 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 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 second argument (if any) 267specifies the radix for the result and the third argument (if any) 268specifies the minimum number of digits in the result. 269.It Fn expr expr 270This is an alias for 271.Ic eval . 272.It Fn format formatstring arg1 ... 273Returns 274.Fa formatstring 275with escape sequences substituted with 276.Fa arg1 277and following arguments, in a way similar to 278.Xr printf 3 . 279This built-in is only available in GNU-m4 compatibility mode, and the only 280parameters implemented are there for autoconf compatibility: 281left-padding flag, an optional field width, a maximum field width, 282*-specified field widths, and the %s and %c data type. 283.It Fn ifdef name yes no 284If the macro named by the first argument is defined then return the second 285argument, otherwise the third. 286If there is no third argument, the value is 287.Dv NULL . 288The word 289.Qq unix 290is predefined. 291.It Fn ifelse a b yes ... 292If the first argument 293.Fa a 294matches the second argument 295.Fa b 296then 297.Fn ifelse 298returns 299the third argument 300.Fa yes . 301If the match fails the three arguments are 302discarded and the next three arguments are used until there is 303zero or one arguments left, either this last argument or 304.Dv NULL 305is returned if no other matches were found. 306.It Fn include name 307Returns the contents of the file specified in the first argument. 308If the file is not found as is, look through the include path: 309first the directories specified with 310.Fl I 311on the command line, then the environment variable 312.Ev M4PATH , 313as a colon-separated list of directories. 314Include aborts with an error message if the file cannot be included. 315.It Fn incr arg 316Increments the argument by 1. 317The argument must be a valid numeric string. 318.It Fn index string substring 319Returns the index of the second argument in the first argument (e.g., 320.Ic index(the quick brown fox jumped, fox) 321returns 16). 322If the second 323argument is not found index returns \-1. 324.It Fn indir macro arg1 ... 325Indirectly calls the macro whose name is passed as the first argument, 326with the remaining arguments passed as first, ... arguments. 327.It Fn len arg 328Returns the number of characters in the first argument. 329Extra arguments 330are ignored. 331.It Fn m4exit code 332Immediately exits with the return value specified by the first argument, 3330 if none. 334.It Fn m4wrap todo 335Allows you to define what happens at the final 336.Dv EOF , 337usually for cleanup purposes (e.g., 338.Ic m4wrap("cleanup(tempfile)") 339causes the macro cleanup to be 340invoked after all other processing is done). 341.Pp 342Multiple calls to 343.Fn m4wrap 344get inserted in sequence at the final 345.Dv EOF . 346.It Fn maketemp template 347Invokes 348.Xr mkstemp 3 349on the first argument, and returns the modified string. 350This can be used to create unique 351temporary file names. 352.It Fn paste file 353Includes the contents of the file specified by the first argument without 354any macro processing. 355Aborts with an error message if the file cannot be 356included. 357.It Fn patsubst string regexp replacement 358Substitutes a regular expression in a string with a replacement string. 359Usual substitution patterns apply: an ampersand 360.Pq Sq \&& 361is replaced by the string matching the regular expression. 362The string 363.Sq \e# , 364where 365.Sq # 366is a digit, is replaced by the corresponding back-reference. 367.It Fn popdef arg ... 368Restores the 369.Ic pushdef Ns ed 370definition for each argument. 371.It Fn pushdef macro def 372Takes the same arguments as 373.Ic define , 374but it saves the definition on a 375stack for later retrieval by 376.Fn popdef . 377.It Fn regexp string regexp replacement 378Finds a regular expression in a string. 379If no further arguments are given, 380it returns the first match position or \-1 if no match. 381If a third argument 382is provided, it returns the replacement string, with sub-patterns replaced. 383.It Fn shift arg1 ... 384Returns all but the first argument, the remaining arguments are 385quoted and pushed back with commas in between. 386The quoting 387nullifies the effect of the extra scan that will subsequently be 388performed. 389.It Fn sinclude file 390Similar to 391.Ic include , 392except it ignores any errors. 393.It Fn spaste file 394Similar to 395.Fn paste , 396except it ignores any errors. 397.It Fn substr string offset length 398Returns a substring of the first argument starting at the offset specified 399by the second argument and the length specified by the third argument. 400If no third argument is present it returns the rest of the string. 401.It Fn syscmd cmd 402Passes the first argument to the shell. 403Nothing is returned. 404.It Ic sysval 405Returns the return value from the last 406.Ic syscmd . 407.It Fn traceon arg ... 408Enables tracing of macro expansions for the given arguments, or for all 409macros if no argument is given. 410.It Fn traceoff arg ... 411Disables tracing of macro expansions for the given arguments, or for all 412macros if no argument is given. 413.It Fn translit string mapfrom mapto 414Transliterate the characters in the first argument from the set 415given by the second argument to the set given by the third. 416You cannot use 417.Xr tr 1 418style abbreviations. 419.It Fn undefine name1 ... 420Removes the definition for the macros specified by its arguments. 421.It Fn undivert arg ... 422Flushes the named output queues (or all queues if no arguments). 423.It Ic unix 424A pre-defined macro for testing the OS platform. 425.It Ic __line__ 426Returns the current file's line number. 427.It Ic __file__ 428Returns the current file's name. 429.El 430.Sh STANDARDS 431The 432.Nm 433utility is compliant with the 434.St -p1003.1-2008 435specification. 436.Pp 437The flags 438.Op Fl dgIot 439and the macros 440.Ic builtin , 441.Ic esyscmd , 442.Ic expr , 443.Ic format , 444.Ic indir , 445.Ic paste , 446.Ic patsubst , 447.Ic regexp , 448.Ic spaste , 449.Ic unix , 450.Ic __line__ , 451and 452.Ic __file__ 453are extensions to that specification. 454.Pp 455The output format of tracing and of 456.Ic dumpdef 457are not specified in any standard, 458are likely to change and should not be relied upon. 459The current format of tracing is closely modelled on 460.Nm gnu-m4 , 461to allow 462.Nm autoconf 463to work. 464.Pp 465The built-ins 466.Ic pushdef 467and 468.Ic popdef 469handle macro definitions as a stack. 470However, 471.Ic define 472interacts with the stack in an undefined way. 473In this implementation, 474.Ic define 475replaces the top-most definition only. 476Other implementations may erase all definitions on the stack instead. 477.Pp 478All built-ins do expand without arguments in many other 479.Nm m4 . 480.Pp 481Many other 482.Nm 483have dire size limitations with respect to buffer sizes. 484.Sh AUTHORS 485.An -nosplit 486.An Ozan Yigit Aq oz@sis.yorku.ca 487and 488.An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU . 489.Pp 490GNU-m4 compatibility extensions by 491.An Marc Espie Aq espie@cvs.openbsd.org . 492