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