path: root/usr/src/man/man1/m4.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\"
.TH M4 1 "Jul 3, 2007"
.SH NAME
m4 \- macro processor
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/m4\fR [\fB-e\fR] [\fB-s\fR] [\fB-B\fR \fIint\fR] [\fB-H\fR \fIint\fR] [\fB-S\fR \fIint\fR]
     [\fB-T\fR \fIint\fR] [\fB-D\fR\fIname\fR [\fI=val\fR]] ... [\fB-U\fR \fIname\fR] ... [\fIfile\fR]...
.fi

.LP
.nf
\fB/usr/xpg4/bin/m4\fR [\fB-e\fR] [\fB-s\fR] [\fB-B\fR \fIint\fR] [\fB-H\fR \fIint\fR] [\fB-S\fR \fIint\fR]
     [\fB-T\fR \fIint\fR] [\fB-D\fR\fIname\fR [...\fI=val\fR]] [\fB-U\fR \fIname\fR] ... [\fIfile\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBm4\fR utility is a macro processor intended as a front end for C,
assembler, and other languages. Each of the argument files is processed in
order. If there are no files, or if a file is \fB\(mi\fR, the standard input is
read. The processed text is written on the standard output. \fBNote:\fR
\fBm4\fR cannot include more than nine nested files and writes a diagnostic
message if that number is exceeded.
.SS "Macro Syntax"
.sp
.LP
Macro calls have the form:
.sp
.in +2
.nf
\fIname\fR(\fIarg1\fR,\fIarg2\fR, ..., \fIargn\fR)
.fi
.in -2
.sp

.sp
.LP
The open parenthesis character, \fB(\fR, must immediately follow the name of
the macro. If the name of a defined macro is not followed by a \fB(\fR, it is
deemed to be a call of that macro with no arguments. Potential macro names
consist of alphanumeric characters and underscore (\fB_\fR), where the first
character is not a digit.
.sp
.LP
Leading unquoted blanks, TABs, and \fBNEWLINE\fRs are ignored while collecting
arguments. Left and right single quotes are used to quote strings. The value of
a quoted string is the string stripped of the quotes.
.SS "Macro Processing"
.sp
.LP
When a macro name is recognized, its arguments are collected by searching for a
matching right parenthesis. If fewer arguments are supplied than are in the
macro definition, the trailing arguments are taken to be \fINULL\fR. Macro
evaluation proceeds normally during the collection of the arguments, and any
commas or right parentheses that happen to turn up within the value of a nested
call are as effective as those in the original input text. After argument
collection, the value of the macro is pushed back onto the input stream and
rescanned.
.SH OPTIONS
.sp
.LP
The options and their effects are as follows:
.sp
.ne 2
.na
\fB\fB-B\fR\fIint\fR\fR
.ad
.RS 9n
Changes the size of the push-back and argument collection buffers from the
default of \fB4,096\fR.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 9n
Operates interactively. Interrupts are ignored and the output is unbuffered.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR\fIint\fR\fR
.ad
.RS 9n
Changes the size of the symbol table hash array from the default of \fB199\fR.
The size should be prime.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 9n
Enables line sync output for the C preprocessor (\fB#\fRline .\|.\|.\|)
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fIint\fR\fR
.ad
.RS 9n
Changes the size of the call stack from the default of \fB100\fRslots. Macros
take three slots, and non-macro arguments take one.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fIint\fR\fR
.ad
.RS 9n
Changes the size of the token buffer from the default of \fB512\fRbytes.
.RE

.sp
.LP
To be effective, the above flags must appear before any file names and before
any \fB-D\fR or \fB-U\fR flags:
.sp
.ne 2
.na
\fB\fB-D\fR \fIname\fR[\fB=\fR\fBval\fR]\fR
.ad
.RS 17n
Defines \fIname\fR to \fBval\fR or to \fINULL\fR in \fBval\fR's absence.
.RE

.sp
.ne 2
.na
\fB\fB-U\fR\fIname\fR\fR
.ad
.RS 17n
Undefines \fIname\fR.
.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
A path name of a text file to be processed. If no \fIfile\fR is given, or if it
is \(mi, the standard input is read.
.RE

.SH USAGE
.sp
.LP
The \fBm4\fR utility makes available the following built-in macros. These
macros can be redefined, but once this is done the original meaning is lost.
Their values are \fINULL\fR unless otherwise stated.
.sp
.ne 2
.na
\fB\fBchangequote\fR\fR
.ad
.RS 15n
Change quote symbols to the first and second arguments. The symbols can be up
to five characters long. \fBchangequote\fR without arguments restores the
original values (that is, \fB`\|'\fR).
.RE

.sp
.ne 2
.na
\fB\fBchangecom\fR\fR
.ad
.RS 15n
Change left and right comment markers from the default \fB#\fR and
\fBNEWLINE\fR. With no arguments, the comment mechanism is effectively
disabled. With one argument, the left marker becomes the argument and the right
marker becomes \fBNEWLINE\fR. With two arguments, both markers are affected.
Comment markers can be up to five characters long.
.RE

.sp
.ne 2
.na
\fB\fBdecr\fR\fR
.ad
.RS 15n
Returns the value of its argument decremented by 1.
.RE

.sp
.ne 2
.na
\fB\fBdefine\fR\fR
.ad
.RS 15n
The second argument is installed as the value of the macro whose name is the
first argument. Each occurrence of \fB$\fR\fIn\fR in the replacement text,
where \fIn\fR is a digit, is replaced by the \fIn\fR-th argument. Argument 0 is
the name of the macro; missing arguments are replaced by the null string;
\fB$#\fR is replaced by the number of arguments; \fB$*\fR is replaced by a list
of all the arguments separated by commas; \fB$@\fR is like \fB$*\fR, but each
argument is quoted (with the current quotes).
.RE

.sp
.ne 2
.na
\fB\fBdefn\fR\fR
.ad
.RS 15n
Returns the quoted definition of its argument(s). It is useful for renaming
macros, especially built-ins.
.RE

.sp
.ne 2
.na
\fB\fBdivert\fR\fR
.ad
.RS 15n
\fBm4\fR maintains 10 output streams, numbered 0-9. The final output is the
concatenation of the streams in numerical order. Initially stream 0 is the
current stream. The \fBdivert\fR macro changes the current output stream to its
(digit-string) argument. Output diverted to a stream other than 0 through 9 is
discarded.
.RE

.sp
.ne 2
.na
\fB\fBdivnum\fR\fR
.ad
.RS 15n
Returns the value of the current output stream.
.RE

.sp
.ne 2
.na
\fB\fBdnl\fR\fR
.ad
.RS 15n
Reads and discards characters up to and including the next \fBNEWLINE\fR.
.RE

.sp
.ne 2
.na
\fB\fBdumpdef\fR\fR
.ad
.RS 15n
Prints current names and definitions, for the named items, or for all if no
arguments are given.
.RE

.sp
.ne 2
.na
\fB\fBerrprint\fR\fR
.ad
.RS 15n
Prints its argument on the diagnostic output file.
.RE

.sp
.ne 2
.na
\fB\fBifdef\fR\fR
.ad
.RS 15n
If the first argument is defined, the value is the second argument, otherwise
the third. If there is no third argument, the value is \fINULL\fR. The word
\fBunix\fR is predefined.
.RE

.sp
.ne 2
.na
\fB\fBifelse\fR\fR
.ad
.RS 15n
This macro has three or more arguments. If the first argument is the same
string as the second, then the value is the third argument. If not, and if
there are more than four arguments, the process is repeated with arguments 4,
5, 6 and 7. Otherwise, the value is either the fourth string, or, if it is not
present, \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fBinclude\fR\fR
.ad
.RS 15n
Returns the contents of the file named in the argument.
.RE

.sp
.ne 2
.na
\fB\fBincr\fR\fR
.ad
.RS 15n
Returns the value of its argument incremented by 1. The value of the argument
is calculated by interpreting an initial digit-string as a decimal number.
.RE

.sp
.ne 2
.na
\fB\fBindex\fR\fR
.ad
.RS 15n
Returns the position in its first argument where the second argument begins
(zero origin), or \(mi1 if the second argument does not occur.
.RE

.sp
.ne 2
.na
\fB\fBlen\fR\fR
.ad
.RS 15n
Returns the number of characters in its argument.
.RE

.sp
.ne 2
.na
\fB\fBm4exit\fR\fR
.ad
.RS 15n
This macro causes immediate exit from \fBm4\fR. Argument 1, if given, is the
exit code; the default is \fB0\fR.
.RE

.sp
.ne 2
.na
\fB\fBm4wrap\fR\fR
.ad
.RS 15n
Argument 1 is pushed back at final \fBEOF\fR. Example:
\fBm4wrap(`cleanup(\|)')\fR
.RE

.sp
.ne 2
.na
\fB\fBmaketemp\fR\fR
.ad
.RS 15n
Fills in a string of "\fBX\fR" characters in its argument with the current
process \fBID\fR.
.RE

.sp
.ne 2
.na
\fB\fBpopdef\fR\fR
.ad
.RS 15n
Removes current definition of its argument(s), exposing the previous one, if
any.
.RE

.sp
.ne 2
.na
\fB\fBpushdef\fR\fR
.ad
.RS 15n
Like \fBdefine\fR, but saves any previous definition.
.RE

.sp
.ne 2
.na
\fB\fBshift\fR\fR
.ad
.RS 15n
Returns all but its 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 be performed.
.RE

.sp
.ne 2
.na
\fB\fBsinclude\fR\fR
.ad
.RS 15n
This macro is identical to \fBinclude\fR, except that it says nothing if the
file is inaccessible.
.RE

.sp
.ne 2
.na
\fB\fBsubstr\fR\fR
.ad
.RS 15n
Returns a substring of its first argument. The second argument is a zero origin
number selecting the first character; the third argument indicates the length
of the substring. A missing third argument is taken to be large enough to
extend to the end of the first string.
.RE

.sp
.ne 2
.na
\fB\fBsyscmd\fR\fR
.ad
.RS 15n
This macro executes the command given in the first argument. No value is
returned.
.RE

.sp
.ne 2
.na
\fB\fBsysval\fR\fR
.ad
.RS 15n
This macro is the return code from the last call to \fBsyscmd\fR.
.RE

.sp
.ne 2
.na
\fB\fBtranslit\fR\fR
.ad
.RS 15n
Transliterates the characters in its first argument from the set given by the
second argument to the set given by the third. No abbreviations are permitted.
.RE

.sp
.ne 2
.na
\fB\fBtraceon\fR\fR
.ad
.RS 15n
This macro with no arguments, turns on tracing for all macros (including
built-ins). Otherwise, turns on tracing for named macros.
.RE

.sp
.ne 2
.na
\fB\fBtraceoff\fR\fR
.ad
.RS 15n
Turns off trace globally and for any macros specified.
.RE

.sp
.ne 2
.na
\fB\fBundefine\fR\fR
.ad
.RS 15n
Removes the definition of the macro named in its argument.
.RE

.sp
.ne 2
.na
\fB\fBundivert\fR\fR
.ad
.RS 15n
This macro causes immediate output of text from diversions named as arguments,
or all diversions if no argument. Text can be undiverted into another
diversion. Undiverting discards the diverted text.
.RE

.SS "/usr/bin/m4"
.sp
.ne 2
.na
\fB\fBeval\fR\fR
.ad
.RS 8n
Evaluates its argument as an arithmetic expression, using 32-bit signed-integer
arithmetic. The following operators are supported: parentheses, unary -, unary
+, !, ~, *, /, %, +, -, relationals, bitwise &, |, &&, and ||. Octal and hex
numbers can be specified as in C. The second argument specifies the radix for
the result; the default is 10. The third argument  can be used to specify the
minimum number of digits in the result.
.RE

.SS "/usr/xpg4/bin/m4"
.sp
.ne 2
.na
\fB\fBeval\fR\fR
.ad
.RS 8n
Evaluates its argument as an arithmetic expression,  using  32-bit
signed-integer arithmetic. The following operators are supported: parentheses,
unary -, unary +, !, ~, *, /, %, +, -, <<, >>, relationals, bitwise &, |, &&,
and ||. Precedence and associativity are as in C. Octal and hex numbers can
also be specified as in C. The second argument specifies the radix for the
result; the default is 10. The third argument can be used to specify the
minimum number of digits in the result.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRExamples of m4 files
.sp
.LP
If the file \fBm4src\fR contains the lines:

.sp
.in +2
.nf
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
.fi
.in -2
.sp

.sp
.LP
then the command:

.sp
.in +2
.nf
\fBm4 m4src\fR
.fi
.in -2
.sp

.sp
.LP
or the command:

.sp
.in +2
.nf
\fBm4 -U VER m4src\fR
.fi
.in -2
.sp

.sp
.LP
produces the output:

.sp
.in +2
.nf
The value of VER is "VER".
        VER is not defined.

        VER is not 2.
        end
.fi
.in -2
.sp

.sp
.LP
The command:

.sp
.in +2
.nf
\fBm4 -D VER m4src\fR
.fi
.in -2
.sp

.sp
.LP
produces the output:

.sp
.in +2
.nf
The value of VER is "".
        VER is defined to be .

        VER is not 2.
        end
.fi
.in -2
.sp

.sp
.LP
The command:

.sp
.in +2
.nf
\fBm4 -D VER=1 m4src\fR
.fi
.in -2
.sp

.sp
.LP
produces the output:

.sp
.in +2
.nf
The value of VER is "1".
       VER is defined to be 1.
       VER is 1.
       VER is not 2.
       end
.fi
.in -2
.sp

.sp
.LP
The command:

.sp
.in +2
.nf
\fBm4 -D VER=2 m4src\fR
.fi
.in -2
.sp

.sp
.LP
produces the output:

.sp
.in +2
.nf
The value of VER is "2".
        VER is defined to be 2.

        VER is 2.
        end
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(7) for descriptions of the following environment variables
that affect the execution of \fBm4\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred
.RE

.sp
.LP
If the \fBm4exit\fR macro is used, the exit value can be specified by the input
file.

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.SS "\fB/usr/xpg4/bin/m4\fR"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.sp
.LP
.BR as (1),
.BR attributes (7),
.BR environ (7),
.BR standards (7)