man-pages/man1p/m4.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "M4" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" m4 
.SH NAME
m4 \- macro processor (\fBDEVELOPMENT\fP)
.SH SYNOPSIS
.LP
\fBm4\fP \fB[\fP\fB-s\fP\fB][\fP\fB-D\fP
\fIname\fP\fB[\fP\fB=\fP\fIval\fP\fB]]\fP\fB...\fP\fB[\fP\fB-U\fP
\fIname\fP\fB]\fP\fB...\fP \fIfile\fP\fB...
\fP
.SH DESCRIPTION
.LP
The \fIm4\fP 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 standard output.
.SH OPTIONS
.LP
The \fIm4\fP 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 \fB-D\fP and
\fB-U\fP options shall be significant.
.LP
The following options shall be supported:
.TP 7
\fB-s\fP
Enable line synchronization output for the \fIc99\fP preprocessor
phase (that is,
\fB#line\fP directives).
.TP 7
\fB-D\ \fP \fIname\fP\fB[\fP=\fIval\fP\fB]\fP
.sp
Define \fIname\fP to \fIval\fP or to null if = \fIval\fP is omitted.
.TP 7
\fB-U\ \fP \fIname\fP
Undefine \fIname\fP.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
A pathname of a text file to be processed. If no \fIfile\fP is given,
or if it is \fB'-'\fP , the standard input shall be
read.
.sp
.SH STDIN
.LP
The standard input shall be a text file that is used if no \fIfile\fP
operand is given, or if it is \fB'-'\fP .
.SH INPUT FILES
.LP
The input file named by the \fIfile\fP operand shall be a text file.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIm4\fP:
.TP 7
\fILANG\fP
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 internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
Determine 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 and input files).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
The standard output shall be the same as the input files, after being
processed for macro expansion.
.SH STDERR
.LP
The standard error shall be used to display strings with the \fBerrprint\fP
macro, macro tracing enabled by the \fBtraceon\fP
macro, the defined text for macros written by the \fBdumpdef\fP macro,
or for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
The \fIm4\fP 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.
.LP
Macro calls have the form:
.sp
.RS
.nf

\fIname\fP\fB(\fP\fIarg1\fP\fB,\fP \fIarg2\fP\fB, ...,\fP \fIargn\fP\fB)
\fP
.fi
.RE
.LP
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.
.LP
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.
.LP
If a macro name is followed by a left parenthesis, its arguments are
the comma-separated 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.
.LP
Arguments are positionally defined and referenced. The string \fB"$1"\fP
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 \fB"$1"\fP to
\fB"$9"\fP , inclusive. The string \fB"$0"\fP is replaced with the
name of the macro. The string \fB"$#"\fP is replaced by
the number of arguments as a string. The string \fB"$*"\fP is replaced
by a list of all of the arguments, separated by commas.
The string \fB"$@"\fP 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.
.LP
If fewer arguments are supplied than are in the macro definition,
the omitted arguments are taken to be null. It is not an error
if more arguments are supplied than are in the macro definition.
.LP
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 ( \fB'`'\fP ) and the right quoting
string consists of an acute accent ( \fB'"\fP ); see also the \fBchangequote\fP
macro.
.LP
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 \fBchangecom\fP and \fBdnl\fP macros.
.LP
The \fIm4\fP 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 \fIdefining
text\fP refers to the value of the macro: the second argument to the
\fBdefine\fP macro, among other things. Except for the first
argument to the \fBeval\fP macro, all numeric arguments to built-in
macros shall be interpreted as decimal values. The string
values produced as the defining text of the \fBdecr\fP, \fBdivnum\fP,
\fBincr\fP, \fBindex\fP, \fBlen\fP, and \fBsysval\fP
built-in macros shall be in the form of a decimal-constant as defined
in the C language.
.TP 7
\fBchangecom\fP
The \fBchangecom\fP 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 <newline> 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.
.TP 7
\fBchangequote\fP
The \fBchangequote\fP 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, \fB`'\fP). With a single argument,
that argument shall become the begin-quote string and the
<newline> shall become the end-quote string. With two arguments, 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.
.TP 7
\fBdecr\fP
The defining text of the \fBdecr\fP macro shall be its first argument
decremented by 1. It shall be an error to specify an
argument containing any non-numeric characters.
.TP 7
\fBdefine\fP
The second argument shall become the defining text of the macro whose
name is the first argument.
.TP 7
\fBdefn\fP
The defining text of the \fBdefn\fP macro shall be the quoted definition
(using the current quoting strings) of its
arguments.
.TP 7
\fBdivert\fP
The \fIm4\fP 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-numerical order. The
\fBdivert\fP macro shall divert future output to the buffer specified
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 containing any non-numeric characters.
.TP 7
\fBdivnum\fP
The defining text of the \fBdivnum\fP macro shall be the number of
the current output stream as a string.
.TP 7
\fBdnl\fP
The \fBdnl\fP macro shall cause \fIm4\fP to discard all input characters
up to and including the next <newline>.
.TP 7
\fBdumpdef\fP
The \fBdumpdef\fP 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.
.TP 7
\fBerrprint\fP
The \fBerrprint\fP macro shall write its arguments to standard error.
.TP 7
\fBeval\fP
The \fBeval\fP macro shall evaluate its first argument as an arithmetic
expression, using 32-bit signed integer arithmetic.
All of the C-language operators shall be supported, except for: 
.sp
.RS
.nf

\fB[]
->
++
--
(\fP\fItype\fP\fB)
unary *
\fP\fIsizeof\fP\fB,
\&.
?:
unary &
\fP
.fi
.RE
.LP
and all assignment operators. It shall be an error to specify any
of these operators. 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 argument,
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.
.TP 7
\fBifdef\fP
If the first argument to the \fBifdef\fP 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.
.TP 7
\fBifelse\fP
The \fBifelse\fP 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 discarded and processing shall restart with
the remaining arguments.
.TP 7
\fBinclude\fP
The defining text for the \fBinclude\fP macro shall be the contents
of the file named by the first argument. It shall be an
error if the file cannot be read.
.TP 7
\fBincr\fP
The defining text of the \fBincr\fP macro shall be its first argument
incremented by 1. It shall be an error to specify an
argument containing any non-numeric characters.
.TP 7
\fBindex\fP
The defining text of the \fBindex\fP macro shall be the first character
position (as a string) in the first argument where a
string matching the second argument begins (zero origin), or -1 if
the second argument does not occur.
.TP 7
\fBlen\fP
The defining text of the \fBlen\fP macro shall be the length (as a
string) of the first argument.
.TP 7
\fBm4exit\fP
Exit from the \fIm4\fP 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 containing any non-numeric characters.
.TP 7
\fBm4wrap\fP
The first argument shall be processed when EOF is reached. If the
\fBm4wrap\fP macro is used multiple times, the arguments
specified shall be processed in the order in which the \fBm4wrap\fP
macros were processed.
.TP 7
\fBmaketemp\fP
The defining text shall be the first argument, with any trailing \fB'X'\fP
characters replaced with the current process ID
as a string.
.TP 7
\fBpopdef\fP
The \fBpopdef\fP 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.
.TP 7
\fBpushdef\fP
The \fBpushdef\fP macro shall be equivalent to the \fBdefine\fP macro
with the exception that it shall preserve any current
definition for future retrieval using the \fBpopdef\fP macro.
.TP 7
\fBshift\fP
The defining text for the \fBshift\fP macro shall be all of its arguments
except for the first one.
.TP 7
\fBsinclude\fP
The \fBsinclude\fP macro shall be equivalent to the \fBinclude\fP
macro, except that it shall not be an error if the file is
inaccessible.
.TP 7
\fBsubstr\fP
The defining text for the \fBsubstr\fP 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.
.TP 7
\fBsyscmd\fP
The \fBsyscmd\fP 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 \fIm4\fP utility. The exit status value from the command
can be retrieved using the \fBsysval\fP macro.
.TP 7
\fBsysval\fP
The defining text of the \fBsysval\fP macro shall be the exit value
of the utility last invoked by the \fBsyscmd\fP macro (as
a string).
.TP 7
\fBtraceon\fP
The \fBtraceon\fP macro shall enable tracing for the macros specified
as arguments, or, if no arguments are specified, for all
macros. The trace output shall be written to standard error in an
unspecified format.
.TP 7
\fBtraceoff\fP
The \fBtraceoff\fP macro shall disable tracing for the macros specified
as arguments, or, if no arguments are specified, for
all macros.
.TP 7
\fBtranslit\fP
The defining text of the \fBtranslit\fP macro shall be the first argument
with every character that occurs in the second
argument replaced with the corresponding character from the third
argument.
.TP 7
\fBundefine\fP
The \fBundefine\fP macro shall delete all definitions (including those
preserved using the \fBpushdef\fP macro) of the macros
named by its arguments.
.TP 7
\fBundivert\fP
The \fBundivert\fP 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. Undiverting shall discard the
contents of the temporary buffer. It shall be an error to specify
an argument containing any non-numeric characters.
.sp
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred
.sp
.LP
If the \fBm4exit\fP macro is used, the exit value can be specified
by the input file.
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
The \fBdefn\fP macro is useful for renaming macros, especially built-ins.
.SH EXAMPLES
.LP
If the file \fBm4src\fP contains the lines:
.sp
.RS
.nf

\fBThe 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
\fP
.fi
.RE
.LP
then the command
.sp
.RS
.nf

\fBm4 m4src
\fP
.fi
.RE
.LP
or the command:
.sp
.RS
.nf

\fBm4 -U VER m4src
\fP
.fi
.RE
.LP
produces the output:
.sp
.RS
.nf

\fBThe value of VER is "VER".
VER is not defined.
.sp

VER is not 2.
end
\fP
.fi
.RE
.LP
The command:
.sp
.RS
.nf

\fBm4 -D VER m4src
\fP
.fi
.RE
.LP
produces the output:
.sp
.RS
.nf

\fBThe value of VER is "".
VER is defined to be .
.sp

VER is not 2.
end
\fP
.fi
.RE
.LP
The command:
.sp
.RS
.nf

\fBm4 -D VER=1 m4src
\fP
.fi
.RE
.LP
produces the output:
.sp
.RS
.nf

\fBThe value of VER is "1".
VER is defined to be 1.
VER is 1.
VER is not 2.
end
\fP
.fi
.RE
.LP
The command:
.sp
.RS
.nf

\fBm4 -D VER=2 m4src
.sp

produces the output:
The value of VER is "2".
VER is defined to be 2.
.sp

VER is 2.
end
\fP
.fi
.RE
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIc99\fP
.SH 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 .