M4 ( 1 ) USER COMMANDSM4 ( 1 )

NAME

m4 - macro preprocessor

SYNOPSIS

m4 [ options ] [ file ... ]

DESCRIPTION

m4 is a macro processor that reads one or more files, processes them according to their included macro statements, and writes the results to the standard output. If file is omitted or - then the standard input is read.

The original m4 implementation has been preserved. Options related to internal fixed size limitations attest to that.

OPTIONS

-C, --cc
Preprocess for the C language. See cc(1).
-D, --define=name[=value]
Define the macro name to value or null if value is omitted.
-I, --include=directory
Append dir to the list of directories searched for include files. By default only the current directory is searched.
-s, --sync
Enable C language #line syncs.
-U, --undefine=name
Remove the definition for the macro name, if any.
-e, --interactive
Ignore interrupts and unbuffer the standard output. Used for debugging.
-B, --bufsize=size
Set the pushback and argument text buffer size. The default value is 4096 .
-H, --hashsize=size
Set the hash table size. size should be a prime. The default value is 199.
-S, --stacksize=size
Set the macro call stack size. The default value is 100.
-T, --tokensize=size
Set the size of the largest token. The default value is 512.

EXTENDED DESCRIPTION

m4 compares each token from the input against the set of built-in and user-defined macros. If the token matches the name of a macro, then the token is replaced by the macros defining text, if any, and rescanned for matching macro names. Once no portion of the token matches the name of a macro, it is written to standard output. Macros may have arguments, in which case the arguments will be substituted into the defining text before it is rescanned.

Macro calls have the form: name(arg1, arg2, ..., argn). Macro names consist of letters, digits and underscores, where the first character is not a digit. Tokens not of this form are not treated as macro names. The left parenthesis must immediately follow the name of the macro. If a token matching the name of a macro is not followed by a left parenthesis, it will be handled as a use of that macro without arguments.

If a macro name is followed by a left parenthesis, its arguments are the comma-separated tokens between the left parenthesis and the matching right parenthesis. Unquoted blank and newline characters preceding each argument are ignored. All other characters, including trailing blank and newline characters, are retained. Commas enclosed between left and right parenthesis characters do not delimit arguments.

Arguments are positionally defined and referenced. The string $1 in the defining text will be replaced by the first argument. Systems support at least nine arguments; only the first nine can be referenced, using the strings $1 to $9, inclusive. The string $0 will be replaced with the name of the macro. The string $# will be replaced by the number of arguments as a string. The string $* will be replaced by a list of all of the arguments, separated by commas. The string $@ will be replaced by a list of all of the arguments separated by commas, and each argument will be quoted using the current left and right quoting strings.

If fewer arguments are supplied than are in the macro definition, the omitted arguments are taken to be null. It is not an error if more arguments are supplied than are in the macro definition.

No special meaning is given to any characters enclosed between matching left and right quoting strings, but the quoting strings are themselves discarded. By default, the left quoting string consists of a grave accent (`) and the right quoting string consists of an acute accent (') see also the changequote macro.

Comments are written but not scanned for matching macro names; by default, the begin-comment string consists of the number sign character and the end-comment string consists of a newline character. See also the changecom and dnl macros.

m4 makes available the following built-in macros. They can be redefined, but once this is done the original meaning is lost. Their values are null unless otherwise stated.
changecom
Sets the begin- and end-comment strings. With no arguments, the comment mechanism is disabled. With a single argument, that argument becomes the begin-comment string and the newline character becomes the end-comment string. With two arguments, the first argument becomes the begin-comment string and the second argument becomes the end-comment string. Systems support comment strings of at least five characters.
changequote
Sets the begin- and end-quote strings. With no arguments the quote strings are set to the default values (that is, #). With a single argument, that argument becomes the begin-quote string and the newline character becomes the end-quote string. With two arguments, the first argument becomes the begin-quote string and the second argument becomes the end-quote string. Systems support quote strings of at least five characters.
decr
The defining text of the decr macro is its first argument decremented by 1. It is an error to specify an argument containing any non-numeric characters.

SEE ALSO

cc(1), cpp(1)

IMPLEMENTATION

version
m4 (AT&T Labs Research) 1999-10-15
author
Glenn Fowler <gsf@research.att.com >
author
David Korn <dgk@research.att.com>
author
Phong Vo <kpv@research.att.com>
copyright
Copyright © 1986-2010 AT&T Intellectual Property
license
http://www.opensource.org/licenses/cpl1.0.txt