1.\" $NetBSD: m4.1,v 1.23 2012/04/08 22:00:39 wiz Exp $ 2.\" @(#) $OpenBSD: m4.1,v 1.62 2014/04/14 07:00:47 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 $Mdocdate: April 14 2014 $ 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.Pq e.g., Sq \ \&this is a string with a leading space . 92You can change the quote characters with the 93.Ic changequote 94built-in macro. 95.Pp 96Most built-ins do not 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 Oo 102.Pf = Ns Ar value 103.Oc 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[,radix[,minimum]] 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 optional second argument 269.Fa radix 270specifies the radix for the result and the optional third argument 271.Fa minimum 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 351Like 352.Ic mkstemp . 353.It Fn mkstemp template 354Invokes 355.Xr mkstemp 3 356on the first argument, and returns the modified string. 357This can be used to create unique 358temporary file names. 359.It Fn paste file 360Includes the contents of the file specified by the first argument without 361any macro processing. 362Aborts with an error message if the file cannot be 363included. 364.It Fn patsubst string regexp replacement 365Substitutes a regular expression in a string with a replacement string. 366Usual substitution patterns apply: an ampersand 367.Pq Sq \&& 368is replaced by the string matching the regular expression. 369The string 370.Sq \e# , 371where 372.Sq # 373is a digit, is replaced by the corresponding back-reference. 374.It Fn popdef arg ... 375Restores the 376.Ic pushdef Ns ed 377definition for each argument. 378.It Fn pushdef macro def 379Takes the same arguments as 380.Ic define , 381but it saves the definition on a 382stack for later retrieval by 383.Fn popdef . 384.It Fn regexp string regexp replacement 385Finds a regular expression in a string. 386If no further arguments are given, 387it returns the first match position or \-1 if no match. 388If a third argument 389is provided, it returns the replacement string, with sub-patterns replaced. 390.It Fn shift arg1 ... 391Returns all but the first argument, the remaining arguments are 392quoted and pushed back with commas in between. 393The quoting 394nullifies the effect of the extra scan that will subsequently be 395performed. 396.It Fn sinclude file 397Similar to 398.Ic include , 399except it ignores any errors. 400.It Fn spaste file 401Similar to 402.Fn paste , 403except it ignores any errors. 404.It Fn substr string offset length 405Returns a substring of the first argument starting at the offset specified 406by the second argument and the length specified by the third argument. 407If no third argument is present it returns the rest of the string. 408.It Fn syscmd cmd 409Passes the first argument to the shell. 410Nothing is returned. 411.It Ic sysval 412Returns the return value from the last 413.Ic syscmd . 414.It Fn traceon arg ... 415Enables tracing of macro expansions for the given arguments, or for all 416macros if no argument is given. 417.It Fn traceoff arg ... 418Disables tracing of macro expansions for the given arguments, or for all 419macros if no argument is given. 420.It Fn translit string mapfrom mapto 421Transliterate the characters in the first argument from the set 422given by the second argument to the set given by the third. 423You cannot use 424.Xr tr 1 425style abbreviations. 426.It Fn undefine name1 ... 427Removes the definition for the macros specified by its arguments. 428.It Fn undivert arg ... 429Flushes the named output queues (or all queues if no arguments). 430.It Ic unix 431A pre-defined macro for testing the OS platform. 432.It Ic __line__ 433Returns the current file's line number. 434.It Ic __file__ 435Returns the current file's name. 436.El 437.Sh EXIT STATUS 438.Ex -std m4 439.Pp 440But note that the 441.Ic m4exit 442macro can modify the exit status. 443.Sh STANDARDS 444The 445.Nm 446utility is compliant with the 447.St -p1003.1-2008 448specification. 449.Pp 450The flags 451.Op Fl dgIPot 452and the macros 453.Ic builtin , 454.Ic esyscmd , 455.Ic expr , 456.Ic format , 457.Ic indir , 458.Ic paste , 459.Ic patsubst , 460.Ic regexp , 461.Ic spaste , 462.Ic unix , 463.Ic __line__ , 464and 465.Ic __file__ 466are extensions to that specification. 467.Pp 468.Ic maketemp 469is not supposed to be a synonym for 470.Ic mkstemp , 471but instead to be an insecure temporary file name creation function. 472It is marked by 473.St -p1003.1-2008 474as being obsolescent and should not be used if portability is a concern. 475.Pp 476The output format of 477.Ic traceon 478and 479.Ic dumpdef 480are not specified in any standard, 481are likely to change and should not be relied upon. 482The current format of tracing is closely modelled on 483.Nm gnu-m4 , 484to allow 485.Nm autoconf 486to work. 487.Pp 488The built-ins 489.Ic pushdef 490and 491.Ic popdef 492handle macro definitions as a stack. 493However, 494.Ic define 495interacts with the stack in an undefined way. 496In this implementation, 497.Ic define 498replaces the top-most definition only. 499Other implementations may erase all definitions on the stack instead. 500.Pp 501All built-ins do expand without arguments in many other 502.Nm . 503.Pp 504Many other 505.Nm 506have dire size limitations with respect to buffer sizes. 507.Sh AUTHORS 508.An -nosplit 509.An Ozan Yigit Aq Mt oz@sis.yorku.ca 510and 511.An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU . 512.Pp 513GNU-m4 compatibility extensions by 514.An Marc Espie Aq Mt espie@cvs.openbsd.org . 515