Content-type: text/html Man page of m4

m4

Section: User Commands (1)
Index Return to Main Contents
 

NAME

m4 - Preprocesses files, expanding macro definitions  

SYNOPSIS

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

[XPG4-UNIX]  The m4 command is a macro processor used as a preprocessor for C and other languages.
 

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

m4:  XPG4, XPG4-UNIX

Refer to the standards(5) reference page for more information about industry standards and associated tags.
 

OPTIONS

[Compaq]  Makes number the size of the push-back and parameter collection buffers (the default is 4096). [Compaq]  Operates interactively. Interrupts are ignored and the output is not buffered. [Compaq]  Makes number the size of the symbol table hash array (the default is 199). The size must be a prime number. [XPG4-UNIX]  Enables the line sync output for the C preprocessor (#line...). [Compaq]  Makes number the size of the call stack (the default is 800 slots). Macros take three slots, and nonmacro arguments take one. [Compaq]  Makes number the size of the token buffer (the default is 512 bytes). [XPG4-UNIX]  Defines macro as value. If value is not specified, macro becomes null. [XPG4-UNIX]  Undefines a built-in macro or one previously defined with the -D option.

Note

[XPG4-UNIX]  The order of options is significant. If used, the -D or -U options must appear after any other options and before any file operands.


 

OPERANDS

[XPG4-UNIX]  Pathname of a file to be processed. If file is omitted, standard input is used. [XPG4-UNIX]  Read standard input.
 

DESCRIPTION

[XPG4-UNIX]  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, the m4 command reads standard input. It writes the processed macros to standard output.

[XPG4-UNIX]  Macro calls follow the form: macro(argument...)

[XPG4-UNIX]  The left parenthesis must immediately follow macro. 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.

[XPG4-UNIX]  While collecting arguments, the m4 command 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.

[XPG4-UNIX]  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, 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, the m4 command pushes the value of the macro back onto the input stream and scans again.
 

Built-In Macros

[XPG4-UNIX]  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: [XPG4-UNIX]  Replaces the macro macro with the value of new_name. The new_name string can included 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. The name of the macro is $0. 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). [XPG4-UNIX]  Removes the definition of macro (including those preserved using the pushdef macro). [XPG4-UNIX]  Returns the quoted definition of macro. [XPG4-UNIX]  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.

[Compaq]  Note that the word unix is predefined. [XPG4-UNIX]  Redefines macro with new_name as in define, but saves any previous definition. [XPG4-UNIX]  Removes the current definition of macro and returns to the previous definition, if one existed. [XPG4-UNIX]  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. [XPG4-UNIX]  The changequote macro sets the begin and end symbols. With no arguments, the quote strings are set to the default values (that is, `', one grave accent and one apostrophe). 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. The symbols can be up to five bytes long. [XPG4-UNIX]  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. [XPG4-UNIX]  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 zero (0) is the current stream. The m4 command discards output diverted to a stream other than 0 to 9. [XPG4-UNIX]  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. [XPG4-UNIX]  Returns the value of the current output stream. [XPG4-UNIX]  Reads and discards characters up to and including the next newline character. [XPG4-UNIX]  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. [XPG4-UNIX]  Returns the value of its argument incremented by 1. [XPG4-UNIX]  Returns the value of its argument decreased by 1.
"eval(expression[,number1[,number2]])"
[XPG4-UNIX]  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.
[XPG4-UNIX]  Octal and hex numbers can be specified as in C. The optional 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. [XPG4-UNIX]  Returns the number of bytes in string. [Compaq]  Returns the number of displayable characters in string; that is, 2-byte extended characters are counted as one displayable character. [XPG4-UNIX]  Returns the first position in string1, where string2 begins (zero origin), or -1 if the second argument does not occur. [XPG4-UNIX]  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. [XPG4-UNIX]  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. [XPG4-UNIX]  Returns the contents of file or displays an error message if it cannot access the file. [XPG4-UNIX]  Returns the contents of file, but it gives no error message if file is inaccessible. [XPG4-UNIX]  Runs the specified operating system command. No value is returned, but sysval can be used to retrieve the exit value. [XPG4-UNIX]  Returns the return code from the last call to syscmd. [XPG4-UNIX]  Replaces xxxxx in its argument with the current process ID number where xxxxx represents any number of numeric or alphanumeric characters. [XPG4-UNIX]  Exits from m4 immediately, returning the specified exit value (the default is zero (0)). [XPG4-UNIX]  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. [XPG4-UNIX]  Includes message on the diagnostic output file (standard error). [XPG4-UNIX]  Writes to standard output the current names and definitions for the named items or for all items if no arguments are provided. [XPG4-UNIX]  Turns on tracing for macro. If none is named, tracing is turned on for all macro expansions. [XPG4-UNIX]  Turns off trace globally and for any macro specified. Macros specifically traced by traceon can be untraced only by specific calls to traceoff.
 

EXIT STATUS

[XPG4-UNIX]  Successful completion. [XPG4-UNIX]  An error occurred.

[XPG4-UNIX]  If you use the m4exit macro, the input file can specify the exit value.
 

EXAMPLES

To preprocess a C language program with m4 and compile it, enter: m4 prog.m4 >prog.c cc prog.c


 

ENVIRONMENT VARIABLES

The following environment variables affect the execution of m4: [XPG4-UNIX]  Provides a default value for the internationalization variables that are unset or null. If LANG is unset or null, the corresponding value from the default locale is used. If any of the internationalization variables contain an invalid setting, the utility behaves as if none of the variables had been defined. [XPG4-UNIX]  If set to a non-empty string value, overrides the values of all the other internationalization variables. [XPG4-UNIX]  Determines the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments). [XPG4-UNIX]  Determines the locale for the format and contents of diagnostic messages written to standard error. [XPG4-UNIX]  Determines the location of message catalogues for the processing of LC_MESSAGES.
 

SEE ALSO

Commands:  c89(1), cc(1), cpp(1)

Standards:  standards(5)


 

Index

NAME
SYNOPSIS
STANDARDS
OPTIONS
OPERANDS
DESCRIPTION
Built-In Macros
EXIT STATUS
EXAMPLES
ENVIRONMENT VARIABLES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:42:59 GMT, October 02, 2010