NAME

m4 - macro processor (DEVELOPMENT)

 SYNOPSIS

m4 [-s][ -D name[=val]]...[-U name]... file...

 DESCRIPTION

The m4 utility is a macro processor that reads one or more text files, processes them according to their included macro statements, and writes the results to standard output.

 OPTIONS

The m4 utility supports the XBD specification, Utility Syntax Guidelines  , except that the order of the -D and -U options is significant. The following options are supported:

-s

Enable line synchronisation output for the c89 preprocessor phase (that is, #line directives).

-D name[=val]

Define name to val or to null if =val is omitted.

-U name

Undefine name.

 OPERANDS

The following operand is supported:

file

A pathname of a text file to be processed. If no file is given, or if it is "-", the standard input is read.

 STDIN

The standard input is a text file that is used if no file operand is given, or if it is "-".

 INPUT FILES

The input file named by the file operand is a text file.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of m4:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

The standard output is the same as the input files, after being processed for macro expansion.

 STDERR

Used to display strings with the errprint macro, macro tracing enabled by the traceon macro, the defined text for macros written by the dumpdef macro, or for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

The m4 utility 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.

The m4 utility 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

The changecom macro 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

The changequote macro 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.

define

The second argument is specified as the defining text of the macro whose name is the first argument.

defn

The defining text of the defn macro is the quoted definition (using the current quoting strings) of its arguments.

divert

The m4 utility maintains ten temporary buffers, numbered 0 to 9, inclusive. When the last of the input has been processed, any output that has been placed in these buffers will be written to standard output in buffer-numerical order. The divert macro diverts future output to the buffer specified by its argument. Specifying no argument or an argument of 0 resumes the normal output process. Output diverted to a stream other than 0 to 9 is discarded. It is an error to specify an argument containing any non-numeric characters.

divnum

The defining text of the divnum macro is the number of the current output stream as a string.

dnl

The dnl macro causes m4 to discard all input characters up to and including the next newline character.

dumpdef

The dumpdef macro writes the defined text to standard error for each of the macros specified as arguments, or, if no arguments are specified, for all macros.

errprint

The errprint macro writes its arguments to standard error.

eval

The eval macro evaluates its first argument as an arithmetic expression, using 32-bit signed integer arithmetic. All of the C-language operators are supported, except for [], ->, ++, --, (type) unary *, sizeof, ",", ".", "?:" and all assignment operators. It is an error to specify any of these operators. Precedence and associativity are as in C. Systems support octal and hexadecimal numbers as in C. The second argument, if specified, sets the radix for the result; the default is 10. The third argument, if specified, sets the minimum number of digits in the result. It is an error to specify an argument containing any non-numeric characters.

ifdef

If the first argument to the ifdef macro is defined, the defining text is the second argument. Otherwise, the defining text is the third argument, if specified, or the null string, if not.

ifelse

If the first argument (or the defining text of the first argument if it is a macro name) to the ifelse macro is the same as the second argument (or the defining text of the second argument if it is a macro name), then the defining text is the third argument. If there are more than four arguments, the initial comparison of the first and second arguments are repeated for each group of three arguments. If no match is found, the defining text will be the argument following the last set of three compared, otherwise it will be null.

include

The defining text for the include macro is the contents of the file named by the first argument. It is an error if the file cannot be read.

incr

The defining text of the incr macro is its first argument incremented by 1. It is an error to specify an argument containing any non-numeric characters.

index

The defining text of the index macro is the first character position (as a string) in the first argument where a string matching the second argument begins (zero origin), or -1 if the second argument does not occur.

len

The defining text of the len macro is the length (as a string) of the first argument.

m4exit

Exit from the m4 utility. If the first argument is specified, it will be the exit code. The default is zero. It is an error to specify an argument containing any non-numeric characters.

m4wrap

The first argument will be processed when EOF is reached. If the m4wrap macro is used multiple times, the arguments specified will be processed in the order in which the m4wrap macros were processed.

maketemp

The defining text is the first argument, with any trailing capital X characters replaced with the current process ID as a string.

popdef

The popdef macro deletes the current definition of its arguments, replacing it with the previous one. If there is no previous definition, the macro is undefined.

pushdef

The pushdef macro is identical to the define macro with the exception that it preserves any current definition for future retrieval using the popdef macro.

shift

The defining text for the shift macro is all of its arguments except for the first one.

sinclude

The sinclude macro is identical to the include macro, except that it is not an error if the file is inaccessible.

substr

The defining text for the substr macro is the substring of the first argument beginning at the zero-offset character position specified by the second argument. The third argument, if specified, is the number of characters to select; if not specified, the characters from the starting point to the end of the first argument become the defining text. It is not an error to specify a starting point beyond the end of the first argument and the defining text will be null. It is an error to specify an argument containing any non-numeric characters.

syscmd

The syscmd macro interprets its first argument as a shell command line. The defining text is the string result of that command. No output redirection is performed by the m4 utility. The exit status value from the command can be retrieved using the sysval macro.

sysval

The defining text of the sysval macro is the exit value of the utility last invoked by the syscmd macro (as a string).

traceon

The traceon macro enables tracing for the macros specified as arguments, or, if no arguments are specified, for all macros. The trace output is written to standard error in an unspecified format.

traceoff

The traceoff macro disables tracing for the macros specified as arguments, or, if no arguments are specified, for all macros.

translit

The defining text of the translit macro is the first argument with every character that occurs in the second argument replaced with the corresponding character from the third argument.

undefine

The undefine macro deletes all definitions (including those preserved using the pushdef macro) of the macros named by its arguments.

undivert

The undivert macro causes immediate output of any text in temporary buffers named as arguments, or all temporary buffers if no arguments are specified. Buffers can be undiverted into other temporary buffers. Undiverting discards the contents of the temporary buffer. It is an error to specify an argument containing any non-numeric characters.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred

If the m4exit macro is used, the exit value can be specified by the input file.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

The defn macro is useful for renaming macros, especially built-ins.

 EXAMPLES

An example of a single m4 input file capable of generating two output files follows. The file file1.m4 could contain lines such as:

if(VER, 1, do_something)
if(VER, 2, do_something)

The makefile for the program might include:

file1.1.c : file1.m4
            m4 -D VER=1 file1.m4 > file1.1.c
            ...
file1.2.c : file1.m4
            m4 -D VER=2 file1.m4 > file1.2.c
            ...

The -U option can be used to undefine VER. If file1.m4 contains:

if(VER, 1, do_something)
if(VER, 2, do_something)
ifndef(VER, do_something)

then the makefile would contain:

file1.0.c : file1.m4
            m4 -U VER file1.m4 > file1.0.c
            ...
file1.1.c : file1.m4
            m4 -D VER=1 file1.m4 > file1.1.c
            ...
file1.2.c : file1.m4
            m4 -D VER=2 file1.m4 > file1.2.c
            ...

 FUTURE DIRECTIONS

None.

 SEE ALSO

c89.