On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2008-08-21 13:59 @38.103.63.61 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
M4(P) M4(P)
NAME
m4 - macro processor (DEVELOPMENT)
SYNOPSIS
m4 [-s][-D name[=val]]...[-U name]... file...
DESCRIPTION
The m4 utility is a macro processor that shall read one or more text files, process
them according to their included macro statements, and write the results to stan-
dard output.
OPTIONS
The m4 utility shall conform to the Base Definitions volume of
IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines, except that the
order of the -D and -U options shall be significant.
The following options shall be supported:
-s Enable line synchronization output for the c99 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 shall be supported:
file A pathname of a text file to be processed. If no file is given, or if it is
ββ-ββ , the standard input shall be read.
STDIN
The standard input shall be 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 shall be a text file.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of m4:
LANG Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of IEEE Std 1003.1-2001,
Section 8.2, Internationalization Variables for the precedence of interna-
tionalization variables used to determine the values of locale categories.)
LC_ALL If set to a non-empty string value, override the values of all the other
internationalization variables.
LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text
data as characters (for example, single-byte as opposed to multi-byte char-
acters 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 catalogs for the processing of LC_MESSAGES
.
ASYNCHRONOUS EVENTS
Default.
STDOUT
The standard output shall be the same as the input files, after being processed for
macro expansion.
STDERR
The standard error shall be 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 shall compare 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
shall be replaced by the macroβs defining text, if any, and rescanned for matching
macro names. Once no portion of the token matches the name of a macro, it shall be
written to standard output. Macros may have arguments, in which case the arguments
shall be substituted into the defining text before it is rescanned.
Macro calls have the form:
name(arg1, arg2, ..., argn)
Macro names shall consist of letters, digits, and underscores, where the first
character is not a digit. Tokens not of this form shall not be treated as macros.
The application shall ensure that the left parenthesis immediately follows the name
of the macro. If a token matching the name of a macro is not followed by a left
parenthesis, it is handled as a use of that macro without arguments.
If a macro name is followed by a left parenthesis, its arguments are the comma-sep-
arated tokens between the left parenthesis and the matching right parenthesis.
Unquoted <blank>s and <newline>s preceding each argument shall be ignored. All
other characters, including trailing <blank>s and <newline>s, 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 shall be replaced by the first argument. Systems shall support at least nine
arguments; only the first nine can be referenced, using the strings "$1" to "$9" ,
inclusive. The string "$0" is replaced with the name of the macro. The string "$#"
is replaced by the number of arguments as a string. The string "$*" is replaced by
a list of all of the arguments, separated by commas. The string "$@" is replaced
by a list of all of the arguments separated by commas, and each argument is quoted
using the current left and right quoting strings.
If fewer arguments are supplied than are in the macro definition, the omitted argu-
ments 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>. See also the changecom and dnl macros.
The m4 utility shall make available the following built-in macros. They can be
redefined, but once this is done the original meaning is lost. Their values shall
be null unless otherwise stated. In the descriptions below, the term defining text
refers to the value of the macro: the second argument to the define macro, among
other things. Except for the first argument to the eval macro, all numeric argu-
ments to built-in macros shall be interpreted as decimal values. The string values
produced as the defining text of the decr, divnum, incr, index, len, and sysval
built-in macros shall be in the form of a decimal-constant as defined in the C lan-
guage.
changecom
The changecom macro shall set the begin-comment and end-comment strings.
With no arguments, the comment mechanism shall be disabled. With a single
argument, that argument shall become the begin-comment string and the <new-
line> shall become the end-comment string. With two arguments, the first
argument shall become the begin-comment string and the second argument shall
become the end-comment string. Systems shall support comment strings of at
least five characters.
changequote
The changequote macro shall set the begin-quote and end-quote strings. With
no arguments, the quote strings shall be set to the default values (that is,
ββββ). With a single argument, that argument shall become the begin-quote
string and the <newline> shall become the end-quote string. With two argu-
ments, the first argument shall become the begin-quote string and the second
argument shall become the end-quote string. Systems shall support quote
strings of at least five characters.
decr The defining text of the decr macro shall be its first argument decremented
by 1. It shall be an error to specify an argument containing any non-numeric
characters.
define The second argument shall become the defining text of the macro whose name
is the first argument.
defn The defining text of the defn macro shall be the quoted definition (using
the current quoting strings) of its arguments.
divert The m4 utility maintains nine temporary buffers, numbered 1 to 9, inclusive.
When the last of the input has been processed, any output that has been
placed in these buffers shall be written to standard output in buffer-numer-
ical order. The divert macro shall divert future output to the buffer speci-
fied by its argument. Specifying no argument or an argument of 0 shall
resume the normal output process. Output diverted to a stream other than 0
to 9 shall be discarded. It shall be an error to specify an argument con-
taining any non-numeric characters.
divnum The defining text of the divnum macro shall be the number of the current
output stream as a string.
dnl The dnl macro shall cause m4 to discard all input characters up to and
including the next <newline>.
dumpdef
The dumpdef macro shall write 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 shall write its arguments to standard error.
eval The eval macro shall evaluate its first argument as an arithmetic expres-
sion, using 32-bit signed integer arithmetic. All of the C-language
operators shall be supported, except for:
[]
->
++
--
(type)
unary *
sizeof,
.
?:
unary &
and all assignment operators. It shall be an error to specify any of these opera-
tors. Precedence and associativity shall be as in the ISO C standard. Systems shall
support octal and hexadecimal numbers as in the ISO C standard. The second argu-
ment, if specified, shall set the radix for the result; the default is 10. The
third argument, if specified, sets the minimum number of digits in the result. It
shall be an error to specify the second or third argument containing any non-
numeric characters.
ifdef If the first argument to the ifdef macro is defined, the defining text shall
be the second argument. Otherwise, the defining text shall be the third
argument, if specified, or the null string, if not.
ifelse The ifelse macro takes three or more arguments. If the first two arguments
compare as equal strings (after macro expansion of both arguments), the
defining text shall be the third argument. If the first two arguments do not
compare as equal strings and there are three arguments, the defining text
shall be null. If the first two arguments do not compare as equal strings
and there are four or five arguments, the defining text shall be the fourth
argument. If the first two arguments do not compare as equal strings and
there are six or more arguments, the first three arguments shall be dis-
carded and processing shall restart with the remaining arguments.
include
The defining text for the include macro shall be the contents of the file
named by the first argument. It shall be an error if the file cannot be
read.
incr The defining text of the incr macro shall be its first argument incremented
by 1. It shall be an error to specify an argument containing any non-numeric
characters.
index The defining text of the index macro shall be the first character position
(as a string) in the first argument where a string matching the second argu-
ment begins (zero origin), or -1 if the second argument does not occur.
len The defining text of the len macro shall be the length (as a string) of the
first argument.
m4exit Exit from the m4 utility. If the first argument is specified, it is the exit
code. The default is zero. It shall be an error to specify an argument con-
taining any non-numeric characters.
m4wrap The first argument shall be processed when EOF is reached. If the m4wrap
macro is used multiple times, the arguments specified shall be processed in
the order in which the m4wrap macros were processed.
maketemp
The defining text shall be the first argument, with any trailing ββXββ charac-
ters replaced with the current process ID as a string.
popdef The popdef macro shall delete the current definition of its arguments,
replacing that definition with the previous one. If there is no previous
definition, the macro is undefined.
pushdef
The pushdef macro shall be equivalent to the define macro with the exception
that it shall preserve any current definition for future retrieval using the
popdef macro.
shift The defining text for the shift macro shall be all of its arguments except
for the first one.
sinclude
The sinclude macro shall be equivalent to the include macro, except that it
shall not be an error if the file is inaccessible.
substr The defining text for the substr macro shall be the substring of the first
argument beginning at the zero-offset character position specified by the
second argument. The third argument, if specified, shall be the number of
characters to select; if not specified, the characters from the starting
point to the end of the first argument shall become the defining text. It
shall not be an error to specify a starting point beyond the end of the
first argument and the defining text shall be null. It shall be an error to
specify an argument containing any non-numeric characters.
syscmd The syscmd macro shall interpret its first argument as a shell command line.
The defining text shall be the string result of that command. No output
redirection shall be 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 shall be the exit value of the utility
last invoked by the syscmd macro (as a string).
traceon
The traceon macro shall enable tracing for the macros specified as argu-
ments, or, if no arguments are specified, for all macros. The trace output
shall be written to standard error in an unspecified format.
traceoff
The traceoff macro shall disable tracing for the macros specified as argu-
ments, or, if no arguments are specified, for all macros.
translit
The defining text of the translit macro shall be the first argument with
every character that occurs in the second argument replaced with the corre-
sponding character from the third argument.
undefine
The undefine macro shall delete all definitions (including those preserved
using the pushdef macro) of the macros named by its arguments.
undivert
The undivert macro shall cause 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. Undivert-
ing shall discard the contents of the temporary buffer. It shall be an error
to specify an argument containing any non-numeric characters.
EXIT STATUS
The following exit values shall be 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.
The following sections are informative.
APPLICATION USAGE
The defn macro is useful for renaming macros, especially built-ins.
EXAMPLES
If the file m4src contains the lines:
The value of ββVERββ is "VER".
ifdef(ββVERββ, "VER" is defined to be VER., VER is not defined.)
ifelse(VER, 1, "VER" is ββVERββ.)
ifelse(VER, 2, "VER" is ββVERββ., "VER" is not 2.)
end
then the command
m4 m4src
or the command:
m4 -U VER m4src
produces the output:
The value of VER is "VER".
VER is not defined.
VER is not 2.
end
The command:
m4 -D VER m4src
produces the output:
The value of VER is "".
VER is defined to be .
VER is not 2.
end
The command:
m4 -D VER=1 m4src
produces the output:
The value of VER is "1".
VER is defined to be 1.
VER is 1.
VER is not 2.
end
The command:
m4 -D VER=2 m4src
produces the output:
The value of VER is "2".
VER is defined to be 2.
VER is 2.
end
RATIONALE
None.
FUTURE DIRECTIONS
None.
SEE ALSO
c99
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1, 2003 Edition, Standard for Information Technology -- Portable Operating
System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C)
2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The
Open Group. In the event of any discrepancy between this version and the original
IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is
the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
POSIX 2003 M4(P)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2008-08-21 13:59 @38.103.63.61 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)