diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/m4.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/m4.1p | 561 |
1 files changed, 561 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/m4.1p b/man-pages-posix-2003/man1p/m4.1p new file mode 100644 index 0000000..992756d --- /dev/null +++ b/man-pages-posix-2003/man1p/m4.1p @@ -0,0 +1,561 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "M4" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" m4 +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.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 . |