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