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 January 12 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 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 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 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 . 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 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 compliant with the 445.St -p1003.1-2008 446specification. 447.Pp 448The flags 449.Op Fl dgIPot 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. 470It is marked by 471.St -p1003.1-2008 472as being obsolescent and should not be used if portability is a concern. 473.Pp 474The output format of 475.Ic traceon 476and 477.Ic dumpdef 478are not specified in any standard, 479are likely to change and should not be relied upon. 480The current format of tracing is closely modelled on 481.Nm gnu-m4 , 482to allow 483.Nm autoconf 484to work. 485.Pp 486The built-ins 487.Ic pushdef 488and 489.Ic popdef 490handle macro definitions as a stack. 491However, 492.Ic define 493interacts with the stack in an undefined way. 494In this implementation, 495.Ic define 496replaces the top-most definition only. 497Other implementations may erase all definitions on the stack instead. 498.Pp 499All built-ins do expand without arguments in many other 500.Nm . 501.Pp 502Many other 503.Nm 504have dire size limitations with respect to buffer sizes. 505.Sh AUTHORS 506.An -nosplit 507.An Ozan Yigit Aq Mt oz@sis.yorku.ca 508and 509.An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU . 510.Pp 511GNU-m4 compatibility extensions by 512.An Marc Espie Aq Mt espie@cvs.openbsd.org . 513