 |
Index for
Section 1 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
m4(1)
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
-Bnumber
[Tru64 UNIX] Makes number the size of the push-back and parameter
collection buffers (the default is 4096).
-e [Tru64 UNIX] Operates interactively. Interrupts are ignored and the
output is not buffered.
-Hnumber
[Tru64 UNIX] Makes number the size of the symbol table hash array (the
default is 199). The size must be a prime number.
-s [XPG4-UNIX] Enables the line sync output for the C preprocessor
(#line...).
-Snumber
[Tru64 UNIX] Makes number the size of the call stack (the default is
800 slots). Macros take three slots, and nonmacro arguments take one.
-Tnumber
[Tru64 UNIX] Makes number the size of the token buffer (the default is
512 bytes).
-Dmacro[=value]
[XPG4-UNIX] Defines macro as value. If value is not specified, macro
becomes null.
-Umacro
[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
file
[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:
define(macro,new_name)
[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).
undefine(macro...)
[XPG4-UNIX] Removes the definition of macro (including those preserved
using the pushdef macro).
defn(macro...)
[XPG4-UNIX] Returns the quoted definition of macro.
ifdef(macro,true,[false])
[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.
[Tru64 UNIX] Note that the word unix is predefined.
pushdef(macro,new_name)
[XPG4-UNIX] Redefines macro with new_name as in define, but saves any
previous definition.
popdef(macro...)
[XPG4-UNIX] Removes the current definition of macro and returns to the
previous definition, if one existed.
shift(argument...)
[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.
changequote(left,right)
[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.
changecom[left_comment][,right_comment]
[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.
divert(number)
[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.
undivert(number...)
[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.
divnum
[XPG4-UNIX] Returns the value of the current output stream.
dnl [XPG4-UNIX] Reads and discards characters up to and including the next
newline character.
ifelse([string1,string2,true,[false]]...)
[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.
incr(number)
[XPG4-UNIX] Returns the value of its argument incremented by 1.
decr(number)
[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.
len(string)
[XPG4-UNIX] Returns the number of bytes in string.
dlen(string)
[Tru64 UNIX] Returns the number of displayable characters in string;
that is, 2-byte extended characters are counted as one displayable
character.
index(string1,string2)
[XPG4-UNIX] 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)
[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.
translit(string,from,to)
[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.
include(file)
[XPG4-UNIX] Returns the contents of file or displays an error message
if it cannot access the file.
sinclude(file)
[XPG4-UNIX] Returns the contents of file, but it gives no error
message if file is inaccessible.
syscmd(command)
[XPG4-UNIX] Runs the specified operating system command. No value is
returned, but sysval can be used to retrieve the exit value.
sysval
[XPG4-UNIX] Returns the return code from the last call to syscmd.
maketemp(...xxxxx)
[XPG4-UNIX] Replaces xxxxx in its argument with the current process ID
number where xxxxx represents any number of numeric or alphanumeric
characters.
m4exit(value)
[XPG4-UNIX] Exits from m4 immediately, returning the specified exit
value (the default is zero (0)).
m4wrap(last_macro)
[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.
errprint(message)
[XPG4-UNIX] Includes message on the diagnostic output file (standard
error).
dumpdef([macro...])
[XPG4-UNIX] Writes to standard output the current names and
definitions for the named items or for all items if no arguments are
provided.
traceon(macro)
[XPG4-UNIX] Turns on tracing for macro. If none is named, tracing is
turned on for all macro expansions.
traceoff(macro...)
[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
0 [XPG4-UNIX] Successful completion.
>0 [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:
LANG
[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.
LC_ALL
[XPG4-UNIX] If set to a non-empty string value, overrides the values
of all the other internationalization variables.
LC_CTYPE
[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).
LC_MESSAGES
[XPG4-UNIX] Determines the locale for the format and contents of
diagnostic messages written to standard error.
NLSPATH
[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 for
Section 1 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|