1.\" $NetBSD: m4.1,v 1.23 2012/04/08 22:00:39 wiz Exp $ 2.\" @(#) $OpenBSD: m4.1,v 1.64 2017/06/15 13:48:42 bcallah 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 June 21, 2023 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 EGgPs 45.Oo 46.Sm off 47.Fl D Ar name Op No = Ar value 48.Sm on 49.Oc 50.Op Fl d Oo Oo +- Oc Ns Ar flags Oc 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 = Ns Ar value Oc , Fl -define Ns = Ns Ar name Ns Oo = Ns Ar value Oc 102Define the symbol 103.Ar name 104to have some value (or 105.Dv NULL ) . 106.It Fl d Oo Oo +|- Oc Ns Ar flags Oc , Fl -debug Ns = Ns Oo Oo +|- Oc Ns Ar flags Oc 107Set or unset trace flags. 108The trace flags are as follows: 109.Bl -tag -width Ds 110.It Ar a 111print macro arguments. 112.It Ar c 113print macro expansion over several lines. 114.It Ar e 115print result of macro expansion. 116.It Ar f 117print filename location. 118.It Ar l 119print line number. 120.It Ar q 121quote arguments and expansion with the current quotes. 122.It Ar t 123start with all macros traced. 124.It Ar x 125number macro expansions. 126.It Ar V 127turn on all options. 128.El 129.Pp 130If 131.Qq + 132or 133.Qq - 134is used, the specified flags are added to or removed from the set of 135active trace flags, respectively; otherwise, the specified flags 136replace the set of active trace flags. 137.Pp 138Specifying this option without an argument is equivalent to specifying 139it with the argument 140.Qq aeq . 141.Pp 142By default, trace is set to 143.Qq eq . 144.It Fl E , Fl -fatal-warnings 145Set warnings to be fatal. 146When a single 147.Fl E 148flag is specified, if warnings are issued, execution 149continues but 150.Nm 151will exit with a non-zero exit status. 152When multiple 153.Fl E 154flags are specified, execution will halt upon issuing the 155first warning and 156.Nm 157will exit with a non-zero exit status. 158This behavior matches GNU m4 1.4.9 and later. 159.It Fl G , Fl -traditional 160Disable GNU compatibility mode (see 161.Fl g 162below). 163.It Fl g , Fl -gnu 164Enable GNU compatibility mode. 165In this mode, 166.Ic translit 167handles simple character ranges (e.g., 168.Sq a-z ) , 169regular expressions mimic Emacs behavior, 170multiple 171.Ic m4wrap 172calls are handled as a stack, 173the number of diversions is unlimited, 174empty names for macro definitions are allowed, 175.Ic undivert 176can be used to include files, 177and 178.Ic eval 179understands 180.Sq 0rbase:value 181numbers. 182.It Fl I Ar dirname , Fl -include Ns = Ns Ar dirname 183Add directory 184.Ar dirname 185to the include path. 186.It Fl o Ar filename , Fl -error-output Ns = Ns Ar filename 187Send trace output to 188.Ar filename . 189.It Fl P , Fl -prefix-builtins 190Prefix all built-in macros with 191.Sq m4_ . 192For example, instead of writing 193.Ic define , 194use 195.Ic m4_define . 196.It Fl s , Fl -synclines 197Output line synchronization directives, suitable for 198.Xr cpp 1 . 199.It Fl t Ar macro , Fl -trace Ns = Ns Ar macro 200Turn tracing on for 201.Ar macro . 202.It Fl U Ns Ar name , Fl -undefine Ns = Ns Ar name 203Undefine the symbol 204.Ar name . 205.El 206.Sh SYNTAX 207.Nm 208provides the following built-in macros. 209They may be redefined, losing their original meaning. 210Return values are null unless otherwise stated. 211.Bl -tag -width changequote 212.It Fn builtin name 213Calls a built-in by its 214.Fa name , 215overriding possible redefinitions. 216.It Fn changecom startcomment endcomment 217Changes the start comment and end comment sequences. 218Comment sequences may be up to five characters long. 219The default values are the hash sign 220and the newline character. 221.Bd -literal -offset indent 222# This is a comment 223.Ed 224.Pp 225With no arguments, comments are turned off. 226With one single argument, the end comment sequence is set 227to the newline character. 228.It Fn changequote beginquote endquote 229Defines the open quote and close quote sequences. 230Quote sequences may be up to five characters long. 231The default values are the backquote character and the quote 232character. 233.Bd -literal -offset indent 234`Here is a quoted string' 235.Ed 236.Pp 237With no arguments, the default quotes are restored. 238With one single argument, the close quote sequence is set 239to the newline character. 240.It Fn decr arg 241Decrements the argument 242.Fa arg 243by 1. 244The argument 245.Fa arg 246must be a valid numeric string. 247.It Fn define name value 248Define a new macro named by the first argument 249.Fa name 250to have the 251value of the second argument 252.Fa value . 253Each occurrence of 254.Sq $n 255(where 256.Ar n 257is 0 through 9) is replaced by the 258.Ar n Ns 'th 259argument. 260.Sq $0 261is the name of the calling macro. 262Undefined arguments are replaced by a null string. 263.Sq $# 264is replaced by the number of arguments; 265.Sq $* 266is replaced by all arguments comma separated; 267.Sq $@ 268is the same as 269.Sq $* 270but all arguments are quoted against further expansion. 271.It Fn defn name ... 272Returns the quoted definition for each argument. 273This can be used to rename 274macro definitions (even for built-in macros). 275.It Fn divert num 276There are 10 output queues (numbered 0-9). 277At the end of processing 278.Nm 279concatenates all the queues in numerical order to produce the 280final output. 281Initially the output queue is 0. 282The divert 283macro allows you to select a new output queue (an invalid argument 284passed to divert causes output to be discarded). 285.It Ic divnum 286Returns the current output queue number. 287.It Ic dnl 288Discard input characters up to and including the next newline. 289.It Fn dumpdef name ... 290Prints the names and definitions for the named items, or for everything 291if no arguments are passed. 292.It Fn errprint msg 293Prints the first argument on the standard error output stream. 294.It Fn esyscmd cmd 295Passes its first argument to a shell and returns the shell's standard output. 296Note that the shell shares its standard input and standard error with 297.Nm . 298.It Fn eval expr[,radix[,minimum]] 299Computes the first argument as an arithmetic expression using 32-bit 300arithmetic. 301Operators are the standard C ternary, arithmetic, logical, 302shift, relational, bitwise, and parentheses operators. 303You can specify 304octal, decimal, and hexadecimal numbers as in C. 305The optional second argument 306.Fa radix 307specifies the radix for the result and the optional third argument 308.Fa minimum 309specifies the minimum number of digits in the result. 310.It Fn expr expr 311This is an alias for 312.Ic eval . 313.It Fn format formatstring arg1 ... 314Returns 315.Fa formatstring 316with escape sequences substituted with 317.Fa arg1 318and following arguments, in a way similar to 319.Xr printf 3 . 320This built-in is only available in GNU-m4 compatibility mode, and the only 321parameters implemented are there for autoconf compatibility: 322left-padding flag, an optional field width, a maximum field width, 323*-specified field widths, and the %s and %c data type. 324.It Fn ifdef name yes no 325If the macro named by the first argument is defined then return the second 326argument, otherwise the third. 327If there is no third argument, the value is 328.Dv NULL . 329The word 330.Qq unix 331is predefined. 332.It Fn ifelse a b yes ... 333If the first argument 334.Fa a 335matches the second argument 336.Fa b 337then 338.Fn ifelse 339returns 340the third argument 341.Fa yes . 342If the match fails the three arguments are 343discarded and the next three arguments are used until there is 344zero or one arguments left, either this last argument or 345.Dv NULL 346is returned if no other matches were found. 347.It Fn include name 348Returns the contents of the file specified in the first argument. 349If the file is not found as is, look through the include path: 350first the directories specified with 351.Fl I 352on the command line, then the environment variable 353.Ev M4PATH , 354as a colon-separated list of directories. 355Include aborts with an error message if the file cannot be included. 356.It Fn incr arg 357Increments the argument by 1. 358The argument must be a valid numeric string. 359.It Fn index string substring 360Returns the index of the second argument in the first argument (e.g., 361.Ic index(the quick brown fox jumped, fox) 362returns 16). 363If the second 364argument is not found index returns \-1. 365.It Fn indir macro arg1 ... 366Indirectly calls the macro whose name is passed as the first argument, 367with the remaining arguments passed as first, ... arguments. 368.It Fn len arg 369Returns the number of characters in the first argument. 370Extra arguments 371are ignored. 372.It Fn m4exit code 373Immediately exits with the return value specified by the first argument, 3740 if none. 375.It Fn m4wrap todo 376Allows you to define what happens at the final 377.Dv EOF , 378usually for cleanup purposes (e.g., 379.Ic m4wrap("cleanup(tempfile)") 380causes the macro cleanup to be 381invoked after all other processing is done). 382.Pp 383Multiple calls to 384.Fn m4wrap 385get inserted in sequence at the final 386.Dv EOF . 387.It Fn maketemp template 388Like 389.Ic mkstemp . 390.It Fn mkstemp template 391Invokes 392.Xr mkstemp 3 393on the first argument, and returns the modified string. 394This can be used to create unique 395temporary file names. 396.It Fn paste file 397Includes the contents of the file specified by the first argument without 398any macro processing. 399Aborts with an error message if the file cannot be 400included. 401.It Fn patsubst string regexp replacement 402Substitutes a regular expression in a string with a replacement string. 403Usual substitution patterns apply: an ampersand 404.Pq Sq \&& 405is replaced by the string matching the regular expression. 406The string 407.Sq \e# , 408where 409.Sq # 410is a digit, is replaced by the corresponding back-reference. 411.It Fn popdef arg ... 412Restores the 413.Ic pushdef Ns ed 414definition for each argument. 415.It Fn pushdef macro def 416Takes the same arguments as 417.Ic define , 418but it saves the definition on a 419stack for later retrieval by 420.Fn popdef . 421.It Fn regexp string regexp replacement 422Finds a regular expression in a string. 423If no further arguments are given, 424it returns the first match position or \-1 if no match. 425If a third argument 426is provided, it returns the replacement string, with sub-patterns replaced. 427.It Fn shift arg1 ... 428Returns all but the first argument, the remaining arguments are 429quoted and pushed back with commas in between. 430The quoting 431nullifies the effect of the extra scan that will subsequently be 432performed. 433.It Fn sinclude file 434Similar to 435.Ic include , 436except it ignores any errors. 437.It Fn spaste file 438Similar to 439.Fn paste , 440except it ignores any errors. 441.It Fn substr string offset length 442Returns a substring of the first argument starting at the offset specified 443by the second argument and the length specified by the third argument. 444If no third argument is present it returns the rest of the string. 445.It Fn syscmd cmd 446Passes the first argument to the shell. 447Nothing is returned. 448.It Ic sysval 449Returns the return value from the last 450.Ic syscmd . 451.It Fn traceon arg ... 452Enables tracing of macro expansions for the given arguments, or for all 453macros if no argument is given. 454.It Fn traceoff arg ... 455Disables tracing of macro expansions for the given arguments, or for all 456macros if no argument is given. 457.It Fn translit string mapfrom mapto 458Transliterate the characters in the first argument from the set 459given by the second argument to the set given by the third. 460You cannot use 461.Xr tr 1 462style abbreviations. 463.It Fn undefine name1 ... 464Removes the definition for the macros specified by its arguments. 465.It Fn undivert arg ... 466Flushes the named output queues (or all queues if no arguments). 467.It Ic unix 468A pre-defined macro for testing the OS platform. 469.It Ic __line__ 470Returns the current file's line number. 471.It Ic __file__ 472Returns the current file's name. 473.El 474.Sh EXIT STATUS 475.Ex -std m4 476.Pp 477But note that the 478.Ic m4exit 479macro can modify the exit status, as can the 480.Fl E 481flag. 482.Sh SEE ALSO 483.Rs 484.\" 4.4BSD PSD:17 485.%A B. W. Kernighan 486.%A D. M. Ritchie 487.%I AT&T Bell Laboratories 488.%T The M4 Macro Processor 489.%R Computing Science Technical Report 490.%N 59 491.%D July 1977 492.Re 493.Sh STANDARDS 494The 495.Nm 496utility is compliant with the 497.St -p1003.1-2008 498specification. 499.Pp 500The flags 501.Op Fl dEGgIPot 502and the macros 503.Ic builtin , 504.Ic esyscmd , 505.Ic expr , 506.Ic format , 507.Ic indir , 508.Ic paste , 509.Ic patsubst , 510.Ic regexp , 511.Ic spaste , 512.Ic unix , 513.Ic __line__ , 514and 515.Ic __file__ 516are extensions to that specification. 517.Pp 518.Ic maketemp 519is not supposed to be a synonym for 520.Ic mkstemp , 521but instead to be an insecure temporary file name creation function. 522It is marked by 523.St -p1003.1-2008 524as being obsolescent and should not be used if portability is a concern. 525.Pp 526The output format of 527.Ic traceon 528and 529.Ic dumpdef 530are not specified in any standard, 531are likely to change and should not be relied upon. 532The current format of tracing is closely modelled on 533.Nm gnu-m4 , 534to allow 535.Nm autoconf 536to work. 537.Pp 538The built-ins 539.Ic pushdef 540and 541.Ic popdef 542handle macro definitions as a stack. 543However, 544.Ic define 545interacts with the stack in an undefined way. 546In this implementation, 547.Ic define 548replaces the top-most definition only. 549Other implementations may erase all definitions on the stack instead. 550.Pp 551All built-ins do expand without arguments in many other 552.Nm . 553.Pp 554Many other 555.Nm 556have dire size limitations with respect to buffer sizes. 557.Sh AUTHORS 558.An -nosplit 559.An Ozan Yigit Aq Mt oz@sis.yorku.ca 560and 561.An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU . 562.Pp 563GNU-m4 compatibility extensions by 564.An Marc Espie Aq Mt espie@cvs.openbsd.org . 565