Commands Reference, Volume 3

m4 Command

Purpose

Preprocesses files, expanding macro definitions.

Syntax

m4 [ -e] [ -l ] [ -s ] [ -B Number ] [ -D Name [ =Value ] ] ... [ -H Number ] [ -I Directory ] [ -S Number ] [ -T Number ] [ -U Name ] ... [ File ... ]

Description

The m4 command is a macro processor used as a preprocessor for C and other languages. You can use it to process built-in macros or user-defined macros.

Each File parameter is processed in order. If you do not specify a File parameter or if you specify the - (dash) as a file name, the m4 command reads standard input. It writes the processed macros to standard output. Macro calls follow the form:

macroname(argument . . . )

The left parenthesis must immediately follow macroname. If the left parenthesis does not follow the name of a defined macro, the m4 command reads it as a macro call with no arguments. Macro names consist of ASCII alphabetic letters, digits, and the _ (underscore) character. Extended characters are not allowed in macro names. The first character cannot be a digit.

While collecting arguments, the m4 command ignores unquoted leading blanks, tabs, and new-line characters. Use single quotation marks to quote strings. The value of a quoted string is the string with the quotation marks stripped off.

When the m4 command recognizes a macro, it collects arguments by searching for a matching right parenthesis. If you supply fewer arguments than appear in the macro definition, the m4 command considers the trailing arguments in the definition to be null. Macro evaluation proceeds normally during the collection of the arguments. All commas or right parentheses within the value of a nested call are translated literally; they do not need an escape character or quotation marks. After collecting arguments, the m4 command pushes the value of the macro back onto the input stream and scans again.

Built-in Macros

The m4 command makes available the following built-in macros. You may redefine them, but you will lose the original meaning. The values of these macros are null unless otherwise stated:

define(Name,NewName)	Replaces the macro Name with the value of NewName. The NewName string can take the form $n . . . (where n is a digit). In this case, each occurrence of n in the replacement text is replaced by the nth argument of Name. $0 is the name of the macro. The null string replaces missing arguments. The number of arguments replaces $#. A comma-separated list of all arguments replaces $. $@ acts like $, but each argument is quoted with the current quotation character (see changequote).
undefine(Name)	Removes the definition of Name.
defn(Name . . . )	Returns the quoted definition of Name.
pushdef(Name, NewName)	Redefines Name with NewName as in define, but saves any previous definition.
popdef(Name . . . )	Removes the current definition of Name and returns to the previous definition, if one existed.
ifdef(Name,True,[False])	Returns the value of True only if Name is defined and is not defined to be 0, otherwise returns False. If you do not supply False, its value is null.
shift(Argument . . . )	Returns all but the first argument. The other arguments are quoted and pushed back with commas in between. The quoting nullifies the effect of the extra scan that is subsequently performed.
changequote(L,R)	Changes quote symbols to L and R. The symbols can be up to 5 bytes long. changequote without arguments restores the original values (` ').
changecom(L,R)	Changes left and right comment markers from the default # and new-line character to L and R. With no arguments, the comment mechanism is disabled. With one argument, the left marker becomes the parameter and the right marker becomes a new-line character. With two arguments, both markers are affected. Comment markers can be up to 5 bytes long.
divert(Number)	Changes the current output stream to stream Number. There are 10 output streams, numbered 0-9. The final output is the concatenation of the streams in numerical order. Initially, stream 0 is the current stream. The m4 command discards output diverted to a stream other than 0-9.
undivert(Number . . . )	Causes immediate output of text from the specified diversions (or all diversions if there is no argument). Text may be undiverted into another diversion. Undiverting discards the diverted text.
divnum	Returns the value of the current output stream.
dnl	Reads and discards characters up to and including the next new-line character.
ifelse([String1,String2,True,[False]] . . . )	If String1 and String2 are the same then the value is True. If they are not and if there are more than four arguments, the m4 command repeats the process with the additional arguments (4, 5, 6, and 7). Otherwise, the value is either False or null if you provide no value for False.
incr(Number)	Returns the value of its argument incremented by 1.
decr(Number)	Returns the value of its argument decreased by 1.
eval(Expression[,Number1[,Number2]])	Evaluates its first argument as an arithmetic expression, using 32-bit arithmetic. The operators you can use are +, -, *, /,%, ^ (exponentiation), bitwise &, \| , ~, and ^ relationals, and parentheses. Octal and hex numbers can be specified as in C. Number1 specifies the radix for the result of the expression. The default radix is 10. The optional Number2 specifies the minimum number of digits in the result.
len(String)	Returns the number of bytes in String.
dlen(String)	Returns the number of displayable characters in String; that is, two-byte extended characters are counted as one displayable character.
index(String1,String2)	Returns the position in the String1 string where the String2 string begins (zero origin), or -1 if the second parameter does not occur.
substr(String,Position, [Number] )	Returns a substring of String. The beginning of the substring is selected with Position, and Number indicates the length of the substring. Without Number, the substring includes everything to the end of the first string.
translit(String,From,To)	Transliterates the characters in String from the set given by From to the set given by To. No abbreviations are permitted. Two-byte extended characters are correctly mapped into the corresponding replacement characters.
include(File)	Returns the contents of File or displays an error message if it cannot access the file.
sinclude(File)	Returns the contents of File, but it gives no error message if File is inaccessible.
syscmd(Command)	Runs the Command. No value is returned.
sysval	Returns the return code from the last call to syscmd.
maketemp( . . . nnnn . . . )	Replaces nnnn in its argument with the current process ID number.
m4exit(Value)	Exits from m4 immediately, returning the specified exit Value (the default is 0).
m4wrap(LastMacro)	Runs LastMacro after reading the end-of-file character. For example, m4wrap (`cleanup ()') runs the cleanup macro at the end of m4.
errprint(Message)	Includes Message on the diagnostic output file.
dumpdef([Name . . . ])	Writes to standard output the current names and definitions for the named items or for all if no arguments are provided.
traceon(Macro)	Turns on tracing for Macro. If none is named, tracing is turned on for all macros.
traceoff(Macro . . . )	Turns off trace globally and for any Macro specified. Macros specifically traced by traceon can be untraced only by specific calls to traceoff.

Flags

-B Number	Makes the Number variable the size of the push-back and parameter collection buffers (the default is 4096).
-e	Operates interactively. Interrupts are ignored and the output is not buffered.
-H Number	Makes the Number variable the size of the symbol table hash array (the default is 199). The size must be a prime number.
-I Directory	(Uppercase i) Searches the Directory variable first, then searches the directories on the standard list for include (built-in macro) files with names that do not begin with a / (slash).
-l	(Lowercase L) Enables line-numbering output for the assembler (.xline . . .).
-s	Enables the line-sync output for the C preprocessor (#line . . .).
-S Number	Makes the Number variable the size of the call stack (the default is 100 slots). Macros take three slots, and non-macro arguments take one.
-T Number	Makes the Number variable the size of the token buffer (the default is 512 bytes).

The preceding flags must appear before any file names and before any -D or -U flags.

-D Name[=Value]	Defines the Name variable as the Value variable. If the Value variable is not specified, the Name variable becomes null.
-U Name	Undefines a the Name variable previously defined with the -D flag.

Exit Status

This command returns the following exit values:

0	Successful completion.
>0	An error occurred.

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

Examples

To preprocess a C language program with the m4 command and compile it, enter:

m4 prog.m4 > prog.c
cc prog.c

Files

/usr/ccs/bin/m4

Contains the m4 command.

Related Information

The m4 Macro Processor Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

The Commands Overview in AIX 5L Version 5.2 System User's Guide: Operating System and Devices.

The as command, cc command, cpp command.