OSF

NAME

m4 − Preprocesses files, expanding macro definitions

SYNOPSIS

m4 [-Bnumber] [-es] [-Snumber] [-Tnumber] [-Dmacro][=value] [-Umacro]
file ...  | -

The m4 command is a macro processor used as a preprocessor for C and other languages. 

FLAGS

-Bnumber
Makes number the size of the push-back and parameter collection buffers (the default is 4096). 

-eOperates interactively.  Interrupts are ignored and the output is not buffered. 

-Hnumber
Makes number the size of the symbol table hash array (the default is 199).  The size must be a prime number. 

-sEnables the line sync output for the C preprocessor (#line...). 

-Snumber
Makes number the size of the call stack (the default is 800 slots).  Macros take three slots, and nonmacro arguments take one. 

-Tnumber
Makes number the size of the token buffer (the default is 512 bytes). 

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

-Dmacro[=value]
Defines macro as value.  If value is not specified, macro becomes null. 

-UmacroUndefines a built-in macro or one previously defined with the -D flag. 

DESCRIPTION

You can use m4 to process built-in macros or user-defined macros.  Each file is processed in order.  If you do not specify a file or if you give a - (dash) as a filename, m4 reads standard input.  It writes the processed macros to standard output. 

Macro calls follow the form:

macro(argument...)

The left parenthesis must immediately follow macro.  If the left parenthesis does not follow the name of a defined macro, m4 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, m4 ignores unquoted leading spaces, tabs, and newline characters.  Use ” (single quotes) to quote strings.  The value of a quoted string is the string with the quotation marks stripped off. 

When m4 recognizes a macro, it collects arguments by searching for a matching right parenthesis.  If you supply fewer arguments than appear in the macro definition, m4 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, m4 pushes the value of the macro back onto the input stream and scans again. 

Built-In Macros

The m4 command contains the following built-in macros.  You can redefine them, but they will then lose their original meanings.  The values of these macros are null unless otherwise stated:

define(macro,new_name)
Replaces the macro macro with the value of new_name.  The new_name string can include tokens of the form $n... (where n is a digit).  In this case, each occurrence of $n in the replacement text is replaced by the n-th argument of macro.  $0 is the name of the macro.  The null string replaces missing arguments.  The number of arguments replaces $#.  A list of all arguments, separated by commas, replaces $∗.  The $@ acts like $∗, but each argument is quoted with the current quotation character (see the changequote macro). 

undefine(macro...)
Removes the definition of macro. 

defn(macro...)
Returns the quoted definition of macro. 

pushdef(macro,new_name)
Redefines macro with new_name as in define, but saves any previous definition. 

popdef(macro...)
Removes the current definition of macro and returns to the previous definition, if one existed. 

ifdef(macro,true,[false])
If the first argument is defined, the value is the second argument. Otherwise, the value is the third argument.  If there is no third argument, the value is null. Note that the word unix is predefined. 

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(left,right)
Changes quote symbols to the values of left and right.  The symbols can be up to five bytes long.  changequote without arguments restores the original values (‘ ’). 

changecom[left_comment][,right_comment]
Changes left and right comment markers from the default # and newline character to left_comment and right_comment.  With no arguments, the comment mechanism is disabled.  With one argument, the left marker becomes the parameter and the right marker becomes a newline 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 to 9.  The final output is the concatenation of the streams in numerical order.  Initially, stream 0 (zero) is the current stream.  m4 discards output diverted to a stream other than 0 to 9. 

undivert(number...)
Causes immediate output of text from the specified diversions (or all diversions if there is no argument).  Text can be undiverted into another diversion.  Undiverting discards the diverted text.

divnumReturns the value of the current output stream. 

dnlReads and discards characters up to and including the next newline 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, m4 repeats the process with the additional arguments (4, 5, 6, and so on).  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 (long) arithmetic.  The operators you can use include +, −, ∗, /, %, ^ (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.  The default is 1. 

len(string)
Returns the number of bytes in string. 

dlen(string)
Returns the number of displayable characters in string; that is, 2-byte extended characters are counted as one displayable character. 

index(string1,string2)
Returns the first position in string1, where string2 begins (zero origin), or -1 if the second argument does not occur. 

substr(string,position,[number]l)
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.  2-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 specified operating system command.  No value is returned.

sysvalReturns the return code from the last call to syscmd. 

maketemp(...xxxxx...)
Replaces xxxxx in its argument with the current process ID number. 

m4exit(value)
Exits from m4 immediately, returning the specified exit value (the default is 0 (zero)). 

m4wrap(last_macro)
Sets or resets last_macro, which is run after reading the End-of-File character.  For example:  m4wrap(‘cleanup()’) sets the cleanup macro at the end of m4. 

errprint(message)
Includes message on the diagnostic output file (standard error). 

dumpdef([macro...])
Writes to standard output the current names and definitions for the named items or for all items if no arguments are provided.

traceon(macro)
Turns on tracing for macro.  If none is named, tracing is turned on for all macro expansions. 

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. 

EXAMPLES

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

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

EXIT VALUES

For information about exit values, see the built-in macro m4exit. 

RELATED INFORMATION

OSF/1 User’s Guide. 

The as, gcc (cc), gdb, and ld commands may be available on your system, but are not provided with OSF/1.