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