1.\" @(#) $OpenBSD: m4.1,v 1.24 2002/04/18 18:57:23 espie Exp $ 2.\" $FreeBSD$ 3.\" 4.Dd April 17, 2002 5.Dt M4 1 6.Os 7.Sh NAME 8.Nm m4 9.Nd macro language processor 10.Sh SYNOPSIS 11.Nm 12.Op Fl d Ar flags 13.Op Fl t Ar name 14.Op Fl gs 15.Op Fl D Ar name Ns Op = Ns Ar value 16.Op Fl U Ar name 17.Op Fl I Ar dirname 18.Op Ar 19.Sh DESCRIPTION 20The 21.Nm 22utility is a macro processor that can be used as a front end to any 23language (e.g., C, ratfor, fortran, lex, and yacc). 24.Nm 25reads from the standard input and writes 26the processed text to the standard output. 27.Pp 28Macro calls have the form 29.Ic name Ns Pq Ar argument1 Ns Op , Ar argument2 , ... , argumentN . 30.Pp 31There cannot be any space following the macro name and the open 32parenthesis 33.Pq Ql \&( . 34If the macro name is not followed by an open 35parenthesis it is processed with no arguments. 36.Pp 37Macro names consist of a leading alphabetic or underscore 38possibly followed by alphanumeric or underscore characters, e.g., 39valid macro names match the pattern 40.Dq Li [a-zA-Z_][a-zA-Z0-9_]* . 41.Pp 42In arguments to macros, leading unquoted space, tab, and newline 43.Pq Ql \en 44characters are ignored. 45To quote strings, use left and right single 46quotes (e.g., 47.Sq "\ this is a string with a leading space" ) . 48You can change the quote characters with the 49.Ic changequote 50built-in macro. 51.Pp 52Most built-ins do not make any sense without arguments, and hence are not 53recognized as special when not followed by an open parenthesis. 54.Pp 55The options are as follows: 56.Bl -tag -width indent 57.It Fl s 58Emit 59.Ic #line 60directives for 61.Xr cpp 1 . 62.It Fl D Ar name Ns Op = Ns Ar value 63Define the symbol 64.Ar name 65to have some value (or 66.Dv NULL ) . 67.It Fl U Ar name 68Undefine the symbol 69.Ar name . 70.It Fl I Ar dirname 71Add directory 72.Ar dirname 73to the include path. 74.It Fl d Ar flags 75Set trace flags. 76The 77.Ar flags 78argument may hold the following: 79.Pp 80.Bl -tag -width indent -compact 81.It Cm a 82print macro arguments 83.It Cm c 84print macro expansion over several lines 85.It Cm e 86print result of macro expansion 87.It Cm f 88print filename location 89.It Cm l 90print line number 91.It Cm q 92quote arguments and expansion with the current quotes 93.It Cm t 94start with all macros traced 95.It Cm x 96number macro expansions 97.It Cm V 98turn on all options 99.El 100.Pp 101By default, trace is set to 102.Cm eq . 103.It Fl t Ar macro 104Turn tracing on for 105.Ar macro . 106.It Fl g 107Activate GNU-m4 compatibility mode. 108In this mode, 109.Ic changequote 110with two empty parameters deactivates quotes, 111.Ic translit 112handles simple character ranges (e.g., 113.Li a-z ) , 114regular expressions mimic 115.Xr emacs 1 116behavior, 117and the number of diversions is unlimited. 118.El 119.Sh SYNTAX 120The 121.Nm 122utility provides the following built-in macros. 123They may be redefined, losing their original meaning. 124Return values are null unless otherwise stated. 125.Bl -tag -width ".Ic changequote" 126.It Ic builtin 127Calls a built-in by its name, overriding possible redefinitions. 128.It Ic changecom 129Changes the start and end comment sequences. 130The default is the pound sign 131.Pq Ql # 132and the newline character. 133With no arguments, the comment sequence is reset to the default, 134in GNU 135.Nm 136mode, comments are turned off. 137The maximum length for a comment marker is five characters. 138.It Ic changequote 139Defines the quote symbols to be the first and second arguments. 140The symbols may be up to five characters long. 141If no arguments are 142given it restores the default open and close single quotes. 143.It Ic decr 144Decrements the argument by 1. 145The argument must be a valid numeric string. 146.It Ic define 147Define a new macro named by the first argument to have the 148value of the second argument. 149Each occurrence of 150.Sq Li $ Ns Ar n 151(where 152.Ar n 153is 0 through 9) is replaced by the 154.Ar n Ns 'th 155argument. 156.Ql $0 157is the name of the calling macro. 158Undefined arguments are replaced by a null string. 159.Ql $# 160is replaced by the number of arguments; 161.Ql $* 162is replaced by all arguments comma separated; 163.Ql $@ 164is the same as 165.Ql $* 166but all arguments are quoted against further expansion. 167.It Ic defn 168Returns the quoted definition for each argument. 169This can be used to rename 170macro definitions (even for built-in macros). 171.It Ic divert 172There are 10 output queues (numbered 0-9). 173At the end of processing 174.Nm 175concatenates all the queues in numerical order to produce the 176final output. 177Initially the output queue is 0. 178The 179.Ic divert 180macro allows you to select a new output queue (an invalid argument 181passed to 182.Ic divert 183causes output to be discarded). 184.It Ic divnum 185Returns the current output queue number. 186.It Ic dnl 187Discards input characters up to and including the next newline. 188.It Ic dumpdef 189Prints the names and definitions for the named items, or for everything 190if no arguments are passed. 191.It Ic errprint 192Prints the first argument on the standard error output stream. 193.It Ic esyscmd 194Passes its first argument to a shell and returns the shell's standard output. 195Note that the shell shares its standard input and standard error with 196.Nm . 197.It Ic eval 198Computes the first argument as an arithmetic expression using 32-bit 199arithmetic. 200Operators are the standard C ternary, arithmetic, logical, 201shift, relational, bitwise, and parentheses operators. 202You can specify 203octal, decimal, and hexadecimal numbers as in C. 204The second argument (if any) 205specifies the radix for the result, and the third argument (if any) 206specifies the minimum number of digits in the result. 207.It Ic expr 208This is an alias for 209.Ic eval . 210.It Ic ifdef 211If the macro named by the first argument is defined then return the second 212argument, otherwise the third. 213If there is no third argument, the value is 214.Dv NULL . 215The word 216.Ic unix 217is predefined. 218.It Ic ifelse 219If the first argument matches the second argument then 220.Ic ifelse 221returns 222the third argument. 223If the match fails, the three arguments are 224discarded and the next three arguments are used until there is 225zero or one arguments left, either this last argument or 226.Dv NULL 227is returned if no other matches were found. 228.It Ic include 229Returns the contents of the file specified in the first argument. 230If the file is not found as is, look through the include path: 231first the directories specified with 232.Fl I 233on the command line, then the environment variable 234.Ev M4PATH , 235as a colon-separated list of directories. 236Aborts with an error message if the file cannot be included. 237.It Ic incr 238Increments the argument by 1. 239The argument must be a valid numeric string. 240.It Ic index 241Returns the index of the second argument in the first argument (e.g., 242.Fn index "the quick brown fox jumped" fox 243returns 16). 244If the second 245argument is not found, 246.Ic index 247returns \-1. 248.It Ic indir 249Indirectly calls the macro whose name is passed as the first arguments, 250with the remaining arguments passed as first, etc. arguments. 251.It Ic len 252Returns the number of characters in the first argument. 253Extra arguments 254are ignored. 255.It Ic m4exit 256Immediately exits with the return value specified by the first argument, 2570 if none. 258.It Ic m4wrap 259Allows you to define what happens at the final 260.Dv EOF , 261usually for cleanup purposes (e.g., 262.Fn m4wrap cleanup(tempfile) 263causes the macro 264.Ic cleanup 265to be 266invoked after all other processing is done). 267.It Ic maketemp 268Translates the string 269.Dq Li XXXXX 270in the first argument with the current process 271ID leaving other characters alone. 272This can be used to create unique 273temporary file names. 274.It Ic paste 275Includes the contents of the file specified by the first argument without 276any macro processing. 277Aborts with an error message if the file cannot be 278included. 279.It Ic patsubst 280Substitutes a regular expression in a string with a replacement string. 281Usual substitution patterns apply: an ampersand 282.Pq Ql & 283is replaced by the string matching the regular expression. 284The string 285.Sq \e Ns Ar # , 286where 287.Ar # 288is a digit, is replaced by the corresponding back-reference. 289.It Ic popdef 290Restores the 291.Ic pushdef Ns ed 292definition for each argument. 293.It Ic pushdef 294Takes the same arguments as 295.Ic define , 296but it saves the definition on a 297stack for later retrieval by 298.Ic popdef . 299.It Ic regexp 300Finds a regular expression in a string. 301If no further arguments are given, 302it returns the first match position or \-1 if no match. 303If a third argument 304is provided, it returns the replacement string, with sub-patterns replaced. 305.It Ic shift 306Returns all but the first argument, the remaining arguments are 307quoted and pushed back with commas in between. 308The quoting 309nullifies the effect of the extra scan that will subsequently be 310performed. 311.It Ic sinclude 312Similar to 313.Ic include , 314except it ignores any errors. 315.It Ic spaste 316Similar to 317.Ic paste , 318except it ignores any errors. 319.It Ic substr 320Returns a substring of the first argument starting at the offset specified 321by the second argument and the length specified by the third argument. 322If no third argument is present it returns the rest of the string. 323.It Ic syscmd 324Passes the first argument to the shell. 325Nothing is returned. 326.It Ic sysval 327Returns the return value from the last 328.Ic syscmd . 329.It Ic traceon 330Enables tracing of macro expansions for the given arguments, or for all 331macros if no argument is given. 332.It Ic traceoff 333Disables tracing of macro expansions for the given arguments, or for all 334macros if no argument is given. 335.It Ic translit 336Transliterate the characters in the first argument from the set 337given by the second argument to the set given by the third. 338You cannot use 339.Xr tr 1 340style abbreviations. 341.It Ic undefine 342Removes the definition for the macros specified by its arguments. 343.It Ic undivert 344Flushes the named output queues (or all queues if no arguments). 345.It Ic unix 346A pre-defined macro for testing the OS platform. 347.It Ic __line__ 348Returns the current file's line number. 349.It Ic __file__ 350Returns the current file's name. 351.El 352.Sh DIAGNOSTICS 353.Ex -std 354.Pp 355The 356.Ic m4exit 357macro may be used to change the exit status from the input file. 358.Sh COMPATIBILITY 359.Nm 360follows the Single Unix 2 specification, along with a few extensions taken 361from GNU-m4. 362Flags 363.Fl I , d , 364and 365.Fl t 366are non-standard. 367.Pp 368The output format of tracing and of 369.Ic dumpdef 370are not specified in any standard, 371are likely to change and should not be relied upon. 372The current format of tracing is closely modelled on GNU-m4, 373to allow 374.Nm autoconf 375to work. 376.Pp 377For portability, one should not use the macros 378.Ic builtin , 379.Ic esycmd , 380.Ic expr , 381.Ic indir , 382.Ic paste , 383.Ic patsubst , 384.Ic regexp , 385.Ic spaste , 386.Ic unix , 387.Ic __line__ , 388and 389.Ic __file__ . 390.Pp 391All built-ins do expand without arguments in many other 392.Nm 393implementations. 394.Pp 395Many other 396.Nm 397implementations have dire size limitations with respect to buffer sizes. 398.Sh STANDARDS 399The 400.Nm 401utility 402conforms to 403.St -p1003.1-2001 . 404.Sh HISTORY 405An 406.Nm 407command appeared in PWB UNIX. 408.Sh AUTHORS 409.An -nosplit 410.An Ozan Yigit Aq oz@sis.yorku.ca 411and 412.An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU . 413GNU-m4 compatibility extensions by 414.An Marc Espie Aq espie@cvs.openbsd.org . 415