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