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