Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
m4.html (39211B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>m4</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ls.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mailx.html" accesskey="N">Next
19 >>></a></td>
20 </tr>
21 </table>
22 <hr align="left" width="100%"></div>
23 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
24 <center><font size="2">The Open Group Base Specifications Issue 8<br>
25 IEEE Std 1003.1-2024<br>
26 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
27 <hr size="2" noshade>
28 <a name="top" id="top"></a> <a name="m4" id="m4"></a> <a name="tag_20_74" id="tag_20_74"></a><!-- m4 -->
29 <h4 class="mansect"><a name="tag_20_74_01" id="tag_20_74_01"></a>NAME</h4>
30 <blockquote>m4 — macro processor</blockquote>
31 <h4 class="mansect"><a name="tag_20_74_02" id="tag_20_74_02"></a>SYNOPSIS</h4>
32 <blockquote class="synopsis">
33 <p><code><tt>m4</tt> <b>[</b><tt>-s</tt><b>] [</b><tt>-D</tt> <i>name</i><b>[</b><tt>=</tt><i>val</i><b>]]</b><tt>...</tt>
34 <b>[</b><tt>-U</tt> <i>name</i><b>]</b><tt>...</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b></code></p>
35 </blockquote>
36 <h4 class="mansect"><a name="tag_20_74_03" id="tag_20_74_03"></a>DESCRIPTION</h4>
37 <blockquote>
38 <p>The <i>m4</i> utility is a macro processor that shall read one or more text files, process them according to their included
39 macro statements, and write the results to standard output.</p>
40 </blockquote>
41 <h4 class="mansect"><a name="tag_20_74_04" id="tag_20_74_04"></a>OPTIONS</h4>
42 <blockquote>
43 <p>The <i>m4</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
44 Guidelines</i></a> , except that the order of the <b>-D</b> and <b>-U</b> options shall be significant, and options can be
45 interspersed with operands.</p>
46 <p>The following options shall be supported:</p>
47 <dl compact>
48 <dd></dd>
49 <dt><b>-s</b></dt>
50 <dd>Enable line synchronization output for the <a href="../utilities/c17.html"><i>c17</i></a> preprocessor phase (that is,
51 <b>#line</b> directives).</dd>
52 <dt><b>-D </b><i>name</i><b>[</b>=<i>val</i><b>]</b></dt>
53 <dd><br>
54 Define <i>name</i> to <i>val</i> or to null if =<i>val</i> is omitted.</dd>
55 <dt><b>-U </b><i>name</i></dt>
56 <dd>Undefine <i>name</i>.</dd>
57 </dl>
58 </blockquote>
59 <h4 class="mansect"><a name="tag_20_74_05" id="tag_20_74_05"></a>OPERANDS</h4>
60 <blockquote>
61 <p>The following operand shall be supported:</p>
62 <dl compact>
63 <dd></dd>
64 <dt><i>file</i></dt>
65 <dd>A pathname of a text file to be processed. If no <i>file</i> is given, or if it is <tt>'-'</tt>, the standard input shall be
66 read.</dd>
67 </dl>
68 </blockquote>
69 <h4 class="mansect"><a name="tag_20_74_06" id="tag_20_74_06"></a>STDIN</h4>
70 <blockquote>
71 <p>The standard input shall be a text file that is used if no <i>file</i> operand is given, or if it is <tt>'-'</tt>.</p>
72 </blockquote>
73 <h4 class="mansect"><a name="tag_20_74_07" id="tag_20_74_07"></a>INPUT FILES</h4>
74 <blockquote>
75 <p>The input file named by the <i>file</i> operand shall be a text file.</p>
76 </blockquote>
77 <h4 class="mansect"><a name="tag_20_74_08" id="tag_20_74_08"></a>ENVIRONMENT VARIABLES</h4>
78 <blockquote>
79 <p>The following environment variables shall affect the execution of <i>m4</i>:</p>
80 <dl compact>
81 <dd></dd>
82 <dt><i>LANG</i></dt>
83 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
84 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
85 variables used to determine the values of locale categories.)</dd>
86 <dt><i>LC_ALL</i></dt>
87 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
88 <dt><i>LC_CTYPE</i></dt>
89 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
90 opposed to multi-byte characters in arguments and input files).</dd>
91 <dt><i>LC_MESSAGES</i></dt>
92 <dd><br>
93 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd>
94 <dt><i>NLSPATH</i></dt>
95 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
96 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
97 "0"></dd>
98 </dl>
99 </blockquote>
100 <h4 class="mansect"><a name="tag_20_74_09" id="tag_20_74_09"></a>ASYNCHRONOUS EVENTS</h4>
101 <blockquote>
102 <p>Default.</p>
103 </blockquote>
104 <h4 class="mansect"><a name="tag_20_74_10" id="tag_20_74_10"></a>STDOUT</h4>
105 <blockquote>
106 <p>The standard output shall be the same as the input files, after being processed for macro expansion.</p>
107 </blockquote>
108 <h4 class="mansect"><a name="tag_20_74_11" id="tag_20_74_11"></a>STDERR</h4>
109 <blockquote>
110 <p>The standard error shall be used to display strings with the <b>errprint</b> macro, macro tracing enabled by the <b>traceon</b>
111 macro, the defined text for macros written by the <b>dumpdef</b> macro, or for diagnostic messages.</p>
112 </blockquote>
113 <h4 class="mansect"><a name="tag_20_74_12" id="tag_20_74_12"></a>OUTPUT FILES</h4>
114 <blockquote>
115 <p>None.</p>
116 </blockquote>
117 <h4 class="mansect"><a name="tag_20_74_13" id="tag_20_74_13"></a>EXTENDED DESCRIPTION</h4>
118 <blockquote>
119 <p>The <i>m4</i> utility shall compare each token from the input against the set of built-in and user-defined macros. If the token
120 matches the name of a macro, then the token shall be replaced by the macro's defining text, if any, then scanning for tokens shall
121 resume at the start of the macro's defining text concatenated with the subsequent input. If a token does not match the name of a
122 macro, it shall be written to standard output. Macros may have arguments, in which case the arguments shall be substituted into the
123 defining text before it is rescanned.</p>
124 <p>No special meaning shall be given to characters enclosed between matching left and right quoting strings, other than identifying
125 nested quoting while finding the matching right quoting string, but the outermost quoting strings shall themselves be discarded. By
126 default, the left quoting string consists of a grave accent (backquote) and the right quoting string consists of an acute accent
127 (single-quote); see also the <b>changequote</b> macro.</p>
128 <p>Comments are written but not scanned for matching macro names; by default, the begin-comment string consists of the
129 <number-sign> character and the end-comment string consists of a <newline>. See also the <b>changecom</b> and
130 <b>dnl</b> macros.</p>
131 <p>Name tokens shall consist of the longest possible sequence of letters, digits, and underscores, where the first character is not
132 a digit. Tokens not of this form shall not be treated as name tokens. A macro call is a name token that matches the name of a
133 built-in or user-defined macro. Macro calls can have either of the following forms, which shall be distinguished by whether or not
134 the macro name is immediately followed by a <left-parenthesis>:</p>
135 <pre>
136 <i>name</i><tt>
137 <br>
138 </tt><i>name</i><tt>(</tt><i>arg1</i><tt>, </tt><i>arg2</i><tt>, ..., </tt><i>argn</i><tt>)
139 </tt></pre>
140 <p>The application shall ensure that the <left-parenthesis> immediately follows the name of the macro. If a token matching
141 the name of a macro is not followed by a <left-parenthesis>, it shall be handled as a use of that macro without
142 arguments.</p>
143 <p>If a macro name is followed by a <left-parenthesis>, the subsequent text shall be tokenized and expanded until a token is
144 encountered that is not a quoted string and whose expansion includes a matching unquoted <right-parenthesis>. The expanded
145 text between the <left-parenthesis> and the matching unquoted <right-parenthesis> is the macro's argument text. An
146 unquoted <comma> character within the macro's argument text shall mark the end of one argument and the beginning of the next
147 argument unless the unquoted <comma> is enclosed within a nested unquoted <left-parenthesis>, <right-parenthesis>
148 pair. The unquoted <comma> characters that separate the arguments, and any unquoted white-space characters at the beginning
149 of each argument, shall be discarded. All other characters in the macro's argument text, including any white-space characters at
150 the end of an argument and any nested parenthesized text, shall be retained. The input text containing the macro name, the
151 following <left-parenthesis>, and all tokens up to and including the token whose expansion contained the matching unquoted
152 <right-parenthesis> shall be replaced, and tokenization shall resume on the result of performing argument substition on the
153 macro's defining text followed by any expanded text that followed the matching unquoted <right-parenthesis>. Otherwise, the
154 macro name was not followed by a <left-parenthesis>, and tokenization shall resume on the result of performing argument
155 substitution with zero arguments on the macro's defining text.</p>
156 <p>During argument substitution, arguments shall be positionally defined and referenced. The string <tt>"$1"</tt> in the defining
157 text shall be replaced by the first argument. Systems shall support at least nine arguments; only the first nine can be referenced,
158 using the strings <tt>"$1"</tt> to <tt>"$9"</tt>, inclusive. The string <tt>"$0"</tt> shall be replaced with the name of the macro.
159 The string <tt>"$#"</tt> shall be replaced by the number of arguments as a minimal string of decimal digits (<tt>'0'</tt> if the
160 macro was invoked without being followed by a <left-parenthesis>, otherwise 1 more than the number of unquoted <comma>
161 characters that divided arguments in the macro's argument text). The string <tt>"$*"</tt> shall be replaced by a list of all of the
162 arguments, separated by <comma> characters. The string <tt>"$@"</tt> shall be replaced by a list of all of the arguments
163 separated by <comma> characters, and each argument shall be quoted using the current left and right quoting strings. The
164 string <tt>"${"</tt> produces unspecified behavior.</p>
165 <p>If fewer arguments are supplied than are in the macro definition, the omitted arguments are taken to be null. It is not an error
166 if more arguments are supplied than are in the macro definition.</p>
167 <p>The <i>m4</i> utility shall make available the following built-in macros. They can be redefined, but once this is done the
168 original meaning is lost. Their values shall be null unless otherwise stated. In the descriptions below, the term <i>defining
169 text</i> refers to the value of the macro: the second argument to the <b>define</b> macro, among other things. Except for the first
170 argument to the <b>eval</b> macro, all numeric arguments to built-in macros shall be interpreted as decimal values. The string
171 values produced as the defining text of the <b>decr</b>, <b>divnum</b>, <b>incr</b>, <b>index</b>, <b>len</b>, and <b>sysval</b>
172 built-in macros shall be in the form of a decimal-constant as defined in the C language.</p>
173 <dl compact>
174 <dd></dd>
175 <dt><b>changecom</b></dt>
176 <dd>The <b>changecom</b> macro shall set the begin-comment and end-comment strings. With no arguments, the comment mechanism shall
177 be disabled. With a single non-null argument, that argument shall become the begin-comment and the <newline> shall become the
178 end-comment string. With two non-null arguments, the first argument shall become the begin-comment string and the second argument
179 shall become the end-comment string. The behavior is unspecified if either argument is provided but null, or if either argument
180 includes letters, digits, underscore, or <left-parenthesis>. Systems shall support comment strings of at least five
181 characters.</dd>
182 <dt><b>changequote</b></dt>
183 <dd>The <b>changequote</b> macro shall set the begin-quote and end-quote strings. With no arguments, the quote strings shall be set
184 to the default values (that is, <tt>`'</tt>). The behavior is unspecified if there is a single argument, or if either argument is
185 null or includes letters, digits, underscore, or <left-parenthesis>. With two non-null arguments, the first argument shall
186 become the begin-quote string and the second argument shall become the end-quote string. Systems shall support quote strings of at
187 least five characters.</dd>
188 <dt><b>decr</b></dt>
189 <dd>The defining text of the <b>decr</b> macro shall be its first argument decremented by 1. It shall be an error to specify an
190 argument containing any non-numeric characters. The behavior is unspecified if <b>decr</b> is not immediately followed by a
191 <left-parenthesis>.</dd>
192 <dt><b>define</b></dt>
193 <dd>The second argument shall become the defining text of the macro whose name is the first argument. It is unspecified whether the
194 <b>define</b> macro deletes all prior definitions of the macro named by its first argument or preserves all but the current
195 definition of the macro. The behavior is unspecified if <b>define</b> is not immediately followed by a
196 <left-parenthesis>.</dd>
197 <dt><b>defn</b></dt>
198 <dd>The defining text of the <b>defn</b> macro shall be the quoted definition (using the current quoting strings) of its arguments.
199 The behavior is unspecified if <b>defn</b> is not immediately followed by a <left-parenthesis>.</dd>
200 <dt><b>divert</b></dt>
201 <dd>The <i>m4</i> utility maintains nine temporary buffers, numbered 1 to 9, inclusive. When the last of the input has been
202 processed, any output that has been placed in these buffers shall be written to standard output in buffer-numerical order. The
203 <b>divert</b> macro shall divert future output to the buffer specified by its argument. Specifying no argument or an argument of 0
204 shall resume the normal output process. Output diverted to a stream with a negative number shall be discarded. Behavior is
205 implementation-defined if a stream number larger than 9 is specified. It shall be an error to specify an argument containing any
206 non-numeric characters.</dd>
207 <dt><b>divnum</b></dt>
208 <dd>The defining text of the <b>divnum</b> macro shall be the number of the current output stream as a string.</dd>
209 <dt><b>dnl</b></dt>
210 <dd>The <b>dnl</b> macro shall cause <i>m4</i> to discard all input characters up to and including the next <newline>.</dd>
211 <dt><b>dumpdef</b></dt>
212 <dd>The <b>dumpdef</b> macro shall write the defined text to standard error for each of the macros specified as arguments, or, if
213 no arguments are specified, for all macros.</dd>
214 <dt><b>errprint</b></dt>
215 <dd>The <b>errprint</b> macro shall write its arguments to standard error. The behavior is unspecified if <b>errprint</b> is not
216 immediately followed by a <left-parenthesis>.</dd>
217 <dt><b>eval</b></dt>
218 <dd>The <b>eval</b> macro shall evaluate its first argument as an arithmetic expression, using signed integer arithmetic with at
219 least 32-bit precision. At least the following C-language operators shall be supported, with precedence, associativity, and
220 behavior as described in <a href="../utilities/V3_chap01.html#tag_18_01_02_01"><i>1.1.2.1 Arithmetic Precision and
221 Operations</i></a> :
222 <pre>
223 <tt>()
224 unary +
225 unary -
226 ~
227 <br>
228 !
229 binary *
230 /
231 %
232 binary +
233 binary -
234 <<
235 >>
236 <
237 <=
238 >
239 >=
240 ==
241 !=
242 binary &
243 ^
244 |
245 &&
246 ||
247 </tt></pre>
248 <p>Systems shall support octal and hexadecimal numbers as in the ISO C standard. The second argument, if specified, shall set
249 the radix for the result; if the argument is blank or unspecified, the default is 10. Behavior is unspecified if the radix falls
250 outside the range 2 to 36, inclusive. The third argument, if specified, sets the minimum number of digits in the result. Behavior
251 is unspecified if the third argument is less than zero. It shall be an error to specify the second or third argument containing any
252 non-numeric characters. The behavior is unspecified if <b>eval</b> is not immediately followed by a <left-parenthesis>.</p>
253 </dd>
254 <dt><b>ifdef</b></dt>
255 <dd>If the first argument to the <b>ifdef</b> macro is defined, the defining text shall be the second argument. Otherwise, the
256 defining text shall be the third argument, if specified, or the null string, if not. The behavior is unspecified if <b>ifdef</b> is
257 not immediately followed by a <left-parenthesis>.</dd>
258 <dt><b>ifelse</b></dt>
259 <dd>The <b>ifelse</b> macro takes three or more arguments. If the first two arguments compare as equal strings, the defining text
260 shall be the third argument. If the first two arguments do not compare as equal strings and there are three arguments, the defining
261 text shall be null. If the first two arguments do not compare as equal strings and there are four or five arguments, the defining
262 text shall be the fourth argument. If the first two arguments do not compare as equal strings and there are six or more arguments,
263 the first three arguments shall be discarded and processing shall restart with the remaining arguments. The behavior is unspecified
264 if <b>ifelse</b> is not immediately followed by a <left-parenthesis>.</dd>
265 <dt><b>include</b></dt>
266 <dd>The defining text for the <b>include</b> macro shall be the contents of the file named by the first argument. It shall be an
267 error if the file cannot be read. The behavior is unspecified if <b>include</b> is not immediately followed by a
268 <left-parenthesis>.</dd>
269 <dt><b>incr</b></dt>
270 <dd>The defining text of the <b>incr</b> macro shall be its first argument incremented by 1. It shall be an error to specify an
271 argument containing any non-numeric characters. The behavior is unspecified if <b>incr</b> is not immediately followed by a
272 <left-parenthesis>.</dd>
273 <dt><b>index</b></dt>
274 <dd>The defining text of the <b>index</b> macro shall be the first character position (as a string) in the first argument where a
275 string matching the second argument begins (zero origin), or -1 if the second argument does not occur. The behavior is unspecified
276 if <b>index</b> is not immediately followed by a <left-parenthesis>.</dd>
277 <dt><b>len</b></dt>
278 <dd>The defining text of the <b>len</b> macro shall be the length (as a string) of the first argument. The behavior is unspecified
279 if <b>len</b> is not immediately followed by a <left-parenthesis>.</dd>
280 <dt><b>m4exit</b></dt>
281 <dd>Exit from the <i>m4</i> utility. If the first argument is specified, it shall be the exit code. If no argument is specified,
282 the exit code shall be zero. It shall be an error to specify an argument containing any non-numeric characters. If the first
283 argument is zero or no argument is specified, and an error has previously occurred (for example, a <i>file</i> operand that could
284 not be opened), the exit status shall be non-zero.</dd>
285 <dt><b>m4wrap</b></dt>
286 <dd>The first argument shall be processed when EOF is reached. If the <b>m4wrap</b> macro is used multiple times, the arguments
287 specified shall be processed in the order in which the <b>m4wrap</b> macros were processed. The behavior is unspecified if
288 <b>m4wrap</b> is not immediately followed by a <left-parenthesis>.</dd>
289 <dt><b>mkstemp</b></dt>
290 <dd>The defining text shall be as if it were the resulting pathname after a successful call to the <a href=
291 "../functions/mkstemp.html"><i>mkstemp</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 called with the
292 first argument to the macro invocation. If a file is created, that file shall be closed. If a file could not be created, the
293 <i>m4</i> utility shall write a diagnostic message to standard error and shall continue processing input but its final exit status
294 shall be non-zero; the defining text of the macro shall be the empty string. The behavior is unspecified if <b>mkstemp</b> is not
295 immediately followed by a <left-parenthesis>.</dd>
296 <dt><b>popdef</b></dt>
297 <dd>The <b>popdef</b> macro shall delete the current definition of its arguments, replacing that definition with the previous one.
298 If there is no previous definition, the macro is undefined. The behavior is unspecified if <b>popdef</b> is not immediately
299 followed by a <left-parenthesis>.</dd>
300 <dt><b>pushdef</b></dt>
301 <dd>The <b>pushdef</b> macro shall be equivalent to the <b>define</b> macro with the exception that it shall preserve any current
302 definition for future retrieval using the <b>popdef</b> macro. The behavior is unspecified if <b>pushdef</b> is not immediately
303 followed by a <left-parenthesis>.</dd>
304 <dt><b>shift</b></dt>
305 <dd>The defining text for the <b>shift</b> macro shall be a comma-separated list of its arguments except the first one. Each
306 argument shall be quoted using the current quoting strings. The behavior is unspecified if <b>shift</b> is not immediately followed
307 by a <left-parenthesis>.</dd>
308 <dt><b>sinclude</b></dt>
309 <dd>The <b>sinclude</b> macro shall be equivalent to the <b>include</b> macro, except that it shall not be an error if the file is
310 inaccessible. The behavior is unspecified if <b>sinclude</b> is not immediately followed by a <left-parenthesis>.</dd>
311 <dt><b>substr</b></dt>
312 <dd>The defining text for the <b>substr</b> macro shall be the substring of the first argument beginning at the zero-offset
313 character position specified by the second argument. The third argument, if specified, shall be the number of characters to select;
314 if not specified, the characters from the starting point to the end of the first argument shall become the defining text. It shall
315 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
316 an error to specify an argument containing any non-numeric characters. The behavior is unspecified if <b>substr</b> is not
317 immediately followed by a <left-parenthesis>.</dd>
318 <dt><b>syscmd</b></dt>
319 <dd>The <b>syscmd</b> macro shall interpret its first argument as a shell command line. The defining text shall be the string
320 result of that command. The string result shall not be rescanned for macros while setting the defining text. No output redirection
321 shall be performed by the <i>m4</i> utility. The exit status value from the command can be retrieved using the <b>sysval</b> macro.
322 The behavior is unspecified if <b>syscmd</b> is not immediately followed by a <left-parenthesis>.</dd>
323 <dt><b>sysval</b></dt>
324 <dd>The defining text of the <b>sysval</b> macro shall be the exit value of the utility last invoked by the <b>syscmd</b> macro (as
325 a string).</dd>
326 <dt><b>traceon</b></dt>
327 <dd>The <b>traceon</b> macro shall enable tracing for the macros specified as arguments, or, if no arguments are specified, for all
328 macros. The trace output shall be written to standard error in an unspecified format.</dd>
329 <dt><b>traceoff</b></dt>
330 <dd>The <b>traceoff</b> macro shall disable tracing for the macros specified as arguments, or, if no arguments are specified, for
331 all macros.</dd>
332 <dt><b>translit</b></dt>
333 <dd>The defining text of the <b>translit</b> macro shall be the first argument with every character that occurs in the second
334 argument replaced with the corresponding character from the third argument. If no replacement character is specified for some
335 source character because the second argument is longer than the third argument, that character shall be deleted from the first
336 argument in <b>translit</b>'s defining text. The behavior is unspecified if the <tt>'-'</tt> character appears within the second or
337 third argument anywhere besides the first or last character. The behavior is unspecified if the same character appears more than
338 once in the second argument. The behavior is unspecified if <b>translit</b> is not immediately followed by a
339 <left-parenthesis>.</dd>
340 <dt><b>undefine</b></dt>
341 <dd>The <b>undefine</b> macro shall delete all definitions (including those preserved using the <b>pushdef</b> macro) of the macros
342 named by its arguments. The behavior is unspecified if <b>undefine</b> is not immediately followed by a
343 <left-parenthesis>.</dd>
344 <dt><b>undivert</b></dt>
345 <dd>The <b>undivert</b> macro shall cause immediate output of any text in temporary buffers named as arguments, or all temporary
346 buffers if no arguments are specified. Buffers can be undiverted into other temporary buffers. Undiverting shall discard the
347 contents of the temporary buffer. The behavior is unspecified if an argument contains any non-numeric characters.</dd>
348 </dl>
349 </blockquote>
350 <h4 class="mansect"><a name="tag_20_74_14" id="tag_20_74_14"></a>EXIT STATUS</h4>
351 <blockquote>
352 <p>The following exit values shall be returned:</p>
353 <dl compact>
354 <dd></dd>
355 <dt> 0</dt>
356 <dd>Successful completion.</dd>
357 <dt>>0</dt>
358 <dd>An error occurred</dd>
359 </dl>
360 <p>If the <b>m4exit</b> macro is used, the exit value can be specified by the input file.</p>
361 </blockquote>
362 <h4 class="mansect"><a name="tag_20_74_15" id="tag_20_74_15"></a>CONSEQUENCES OF ERRORS</h4>
363 <blockquote>
364 <p>Default.</p>
365 </blockquote>
366 <hr>
367 <div class="box"><em>The following sections are informative.</em></div>
368 <h4 class="mansect"><a name="tag_20_74_16" id="tag_20_74_16"></a>APPLICATION USAGE</h4>
369 <blockquote>
370 <p>The <b>defn</b> macro is useful for renaming macros, especially built-ins.</p>
371 <p>Since <b>eval</b> defers to the ISO C standard, some operations have undefined behavior. In some implementations, division
372 or remainder by zero cause a fatal signal, even if the division occurs on the short-circuited branch of <tt>"&&"</tt> or
373 <tt>"||"</tt>. Any operation that overflows in signed arithmetic produces undefined behavior. Likewise, using the <b>shift</b>
374 operators with a shift amount that is not positive and smaller than the precision is undefined, as is shifting a negative number to
375 the right. Historically, not all implementations obeyed C-language precedence rules: <tt>'~'</tt> and <tt>'!'</tt> were lower than
376 <tt>'=='</tt>; <tt>'=='</tt> and <tt>'!='</tt> were not lower than <tt>'<'</tt>; and <tt>'|'</tt> was not lower than
377 <tt>'^'</tt>; the liberal use of <tt>"()"</tt> can force the desired precedence even with these non-compliant implementations.
378 Furthermore, some traditional implementations treated <tt>'^'</tt> as an exponentiation operator, although most implementations now
379 use <tt>"**"</tt> as an extension for this purpose.</p>
380 <p>When a macro has been multiply defined via the <b>pushdef</b> macro, it is unspecified whether the <b>define</b> macro will
381 alter only the most recent definition (as though by <b>popdef</b> and <b>pushdef</b>), or replace the entire stack of definitions
382 with a single definition (as though by <b>undefine</b> and <b>pushdef</b>). An application desiring particular behavior for the
383 <b>define</b> macro in this case can redefine it accordingly.</p>
384 </blockquote>
385 <h4 class="mansect"><a name="tag_20_74_17" id="tag_20_74_17"></a>EXAMPLES</h4>
386 <blockquote>
387 <p>If the file <b>m4src</b> contains the lines:</p>
388 <pre>
389 <tt>The value of `VER' is "VER".
390 ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
391 ifelse(VER, 1, ``VER'' is `VER'.)
392 ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
393 end
394 </tt></pre>
395 <p>then the command</p>
396 <pre>
397 <tt>m4 m4src
398 </tt></pre>
399 <p>or the command:</p>
400 <pre>
401 <tt>m4 -U VER m4src
402 </tt></pre>
403 <p>produces the output:</p>
404 <pre>
405 <tt>The value of VER is "VER".
406 VER is not defined.
407 <br>
408 VER is not 2.
409 end
410 </tt></pre>
411 <p>The command:</p>
412 <pre>
413 <tt>m4 -D VER m4src
414 </tt></pre>
415 <p>produces the output:</p>
416 <pre>
417 <tt>The value of VER is "".
418 VER is defined to be .
419 <br>
420 VER is not 2.
421 end
422 </tt></pre>
423 <p>The command:</p>
424 <pre>
425 <tt>m4 -D VER=1 m4src
426 </tt></pre>
427 <p>produces the output:</p>
428 <pre>
429 <tt>The value of VER is "1".
430 VER is defined to be 1.
431 VER is 1.
432 VER is not 2.
433 end
434 </tt></pre>
435 <p>The command:</p>
436 <pre>
437 <tt>m4 -D VER=2 m4src
438 </tt></pre>
439 <p>produces the output:</p>
440 <pre>
441 <tt>The value of VER is "2".
442 VER is defined to be 2.
443 <br>
444 VER is 2.
445 end
446 </tt></pre>
447 <p>In the following six examples, an additional line is evaluated after this prologue of three definitions:</p>
448 <pre>
449 <tt>define(`macro', `argument 2 is :`$2':, called with $# arguments')dnl
450 define(`argumentsa', `Arguments')dnl
451 define(`a', `.')dnl
452 </tt></pre>
453 <ol>
454 <li>
455 <p>The additional line:</p>
456 <pre>
457 <tt>macro`'a
458 </tt></pre>
459 produces:
460 <pre>
461 <tt>argument 2 is ::, called with 0 arguments.
462 </tt></pre>
463 Explanation: <i>macro</i> is called with 0 arguments (as shown by the <tt>$#</tt> substitution), the substitution of <tt>$2</tt> is
464 the empty string, and the empty quoted string after the expansion text prevents concatenation with the subsequent <tt>'a'</tt>,
465 which in turn lets macro <i>a</i> expand to the final <tt>'.'</tt>.</li>
466 <li>
467 <p>The additional line:</p>
468 <pre>
469 <tt>macro()a
470 </tt></pre>
471 produces:
472 <pre>
473 <tt>argument 2 is ::, called with 1 Arguments
474 </tt></pre>
475 Explanation: <i>macro</i> is called with one (empty string) argument; then the defining text ending in <tt>"arguments"</tt> is
476 concatenated with the subsequent <tt>'a'</tt> to form the next macro name <i>argumentsa</i> which is expanded into
477 <tt>Arguments</tt> before the final output.</li>
478 <li>
479 <p>The additional line:</p>
480 <pre>
481 <tt>macro( 1, ( ,2,) , `3')
482 </tt></pre>
483 produces:
484 <pre>
485 <tt>argument 2 is :( ,2,) :, called with 3 arguments
486 </tt></pre>
487 Explanation: Leading (but not internal or trailing) space is removed before the argument substituted for <tt>$2</tt>, and the
488 unquoted commas embedded in parentheses do not delineate arguments.</li>
489 <li>
490 <p>The additional line:</p>
491 <pre>
492 <tt>macro( `1', `mac2(,`2',)', `3')
493 </tt></pre>
494 produces:
495 <pre>
496 <tt>argument 2 is :mac2(,`2',):, called with 3 arguments
497 </tt></pre>
498 Explanation: Regardless of whether <i>mac2</i> is a defined macro, quoting in the macro call prevents interpretation of
499 <tt>"mac2"</tt> during argument collection, and the quoting in the defining text of <i>macro</i> prevents interpretation of
500 <tt>"mac2"</tt> in the substitution of <tt>$2</tt> during rescan of the output of <i>macro</i>.</li>
501 <li>
502 <p>The additional line:</p>
503 <pre>
504 <tt>undefine(`mac2')macro( 1, mac2(,2,), 3)
505 </tt></pre>
506 produces:
507 <pre>
508 <tt>argument 2 is :mac2(,2,):, called with 3 arguments
509 </tt></pre>
510 Explanation: <i>mac2</i> is not a macro name when scanned during argument collection, so it and the subsequent parenthesized text
511 are used literally.</li>
512 <li>
513 <p>The additional line:</p>
514 <pre>
515 <tt>define(`mac2', `hi $@')macro( 1, mac2( ,2,), 3)
516 </tt></pre>
517 produces:
518 <pre>
519 <tt>argument 2 is :hi :, called with 5 arguments
520 </tt></pre>
521 Explanation: <i>mac2</i> is a macro name, so collecting the arguments to <i>macro</i> requires scanning the output of
522 <i>mac2(,2,)</i> (the text <tt>hi `',`2',`'</tt> after substitution of <tt>$@</tt>); this output contains unquoted commas causing
523 additional arguments to be visible to <i>macro</i>.</li>
524 </ol>
525 </blockquote>
526 <h4 class="mansect"><a name="tag_20_74_18" id="tag_20_74_18"></a>RATIONALE</h4>
527 <blockquote>
528 <p>Historic System V-based behavior treated <tt>"${"</tt> in a macro definition as two literal characters. However, this sequence
529 is left unspecified so that implementations may offer extensions such as <tt>"${11}"</tt> meaning the eleventh argument. Macros can
530 still be defined with appropriate uses of nested quoting to result in a literal <tt>"${"</tt> in the output after rescanning
531 removes the nested quotes.</p>
532 <p>In the <b>translit</b> built-in, historic System V-based behavior treated <tt>'-'</tt> as a literal; GNU behavior treats it as a
533 range. This version of the standard allows either behavior.</p>
534 <p>Earlier versions of this standard allowed the exit status to be either zero or non-zero when <tt>m4exit(0)</tt> is called after
535 an error has occurred. Exiting with zero status is now disallowed as this hides the fact that an error occurred from shell scripts
536 that check the exit status of <i>m4</i>.</p>
537 </blockquote>
538 <h4 class="mansect"><a name="tag_20_74_19" id="tag_20_74_19"></a>FUTURE DIRECTIONS</h4>
539 <blockquote>
540 <p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline>
541 character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to
542 treat this as an error. A future version of this standard may require implementations to treat this as an error.</p>
543 </blockquote>
544 <h4 class="mansect"><a name="tag_20_74_20" id="tag_20_74_20"></a>SEE ALSO</h4>
545 <blockquote>
546 <p><a href="../utilities/c17.html#"><i>c17</i></a></p>
547 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
548 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p>
549 </blockquote>
550 <h4 class="mansect"><a name="tag_20_74_21" id="tag_20_74_21"></a>CHANGE HISTORY</h4>
551 <blockquote>
552 <p>First released in Issue 2.</p>
553 </blockquote>
554 <h4 class="mansect"><a name="tag_20_74_22" id="tag_20_74_22"></a>Issue 5</h4>
555 <blockquote>
556 <p>The phrase "the defined text for macros written by the <b>dumpdef</b> macro" is added to the description of STDERR, and the
557 description of <b>dumpdef</b> is updated to indicate that output is written to standard error. The description of <b>eval</b> is
558 updated to indicate that the list of excluded C operators excludes unary <tt>'&'</tt> and <tt>'.'</tt>. In the description of
559 <b>ifdef</b>, the phrase "and it is not defined to be zero" is deleted.</p>
560 </blockquote>
561 <h4 class="mansect"><a name="tag_20_74_23" id="tag_20_74_23"></a>Issue 6</h4>
562 <blockquote>
563 <p>In the EXTENDED DESCRIPTION, the <b>eval</b> text is updated to include a <tt>'&'</tt> character in the excepted list.</p>
564 <p>The EXTENDED DESCRIPTION of <b>divert</b> is updated to clarify that there are only nine diversion buffers.</p>
565 <p>The normative text is reworded to avoid use of the term "must" for application requirements.</p>
566 <p>The Open Group Base Resolution bwg2000-006 is applied.</p>
567 <p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/31 is applied, replacing the EXAMPLES section.</p>
568 </blockquote>
569 <h4 class="mansect"><a name="tag_20_74_24" id="tag_20_74_24"></a>Issue 7</h4>
570 <blockquote>
571 <p>Austin Group Interpretation 1003.1-2001 #117 is applied, marking the <b>maketemp</b> macro obsolescent and adding a new
572 <b>mkstemp</b> macro.</p>
573 <p>Austin Group Interpretation 1003.1-2001 #207 is applied, clarifying the handling of white-space characters that precede or trail
574 any macro arguments.</p>
575 <p>SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply (options can be
576 interspersed with operands).</p>
577 <p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p>
578 <p>SD5-XCU-ERN-99 is applied, clarifying the definition of the <b>divert</b> macro in the EXTENDED DESCRIPTION.</p>
579 <p>SD5-XCU-ERN-100 is applied, clarifying the definition of the <b>syscmd</b> macro in the EXTENDED DESCRIPTION.</p>
580 <p>SD5-XCU-ERN-101 is applied, clarifying the definition of the <b>undivert</b> macro in the EXTENDED DESCRIPTION.</p>
581 <p>SD5-XCU-ERN-111 is applied to the EXTENDED DESCRIPTION, clarifying that the string <tt>"${"</tt> produces unspecified
582 behavior.</p>
583 <p>SD5-XCU-ERN-112 is applied, updating the <b>changequote</b> macro.</p>
584 <p>SD5-XCU-ERN-118 is applied, clarifying the definition of the <b>define</b> macro in the EXTENDED DESCRIPTION and APPLICATION
585 USAGE sections.</p>
586 <p>SD5-XCU-ERN-119 is applied, clarifying the definition of the <b>translit</b> macro in the EXTENDED DESCRIPTION and RATIONALE
587 sections.</p>
588 <p>SD5-XCU-ERN-130, SD5-XCU-ERN-131, and SD5-XCU-ERN-137 are applied.</p>
589 <p>The <i>m4</i> utility is moved from the XSI option to the Base.<br></p>
590 <p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0117 [241], XCU/TC1-2008/0118 [242,431], XCU/TC1-2008/0119 [242,431], and
591 XCU/TC1-2008/0120 [325,430] are applied.</p>
592 <p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0117 [964], XCU/TC2-2008/0118 [970], and XCU/TC2-2008/0119 [964] are
593 applied.</p>
594 </blockquote>
595 <h4 class="mansect"><a name="tag_20_74_25" id="tag_20_74_25"></a>Issue 8</h4>
596 <blockquote>
597 <p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a
598 pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or
599 separator in the output format being used.</p>
600 <p>Austin Group Defect 984 is applied, requiring that the exit status of <i>m4</i> is non-zero when <b>m4exit</b> is called with a
601 first argument of zero or with no arguments after an error has occurred.</p>
602 <p>Austin Group Defect 1072 is applied, clarifying the handling of macro arguments.</p>
603 <p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
604 <p>Austin Group Defect 1330 is applied, removing the obsolescent <b>maketemp</b> macro.</p>
605 <p>Austin Group Defect 1514 is applied, changing the RATIONALE section to use the same terminology as the normative text to which
606 it refers.</p>
607 <p>Austin Group Defect 1570 is applied, removing extra spacing in <tt>"=="</tt>.</p>
608 <p>Austin Group Defect 1658 is applied, changing "whitespace characters" to "white-space characters".</p>
609 <p>Austin Group Defect 1730 is applied, adding square brackets around <i>file</i><tt>...</tt> in the SYNOPSIS.</p>
610 </blockquote>
611 <div class="box"><em>End of informative text.</em></div>
612 <hr>
613 <p> </p>
614 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
615 <hr size="2" noshade>
616 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
617 POSIX™ is a Trademark of The IEEE.<br>
618 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
619 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
620 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
621 ]</font></center>
622 <hr size="2" noshade>
623 <div class="NAVHEADER">
624 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
625 <tr class="nav">
626 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ls.html" accesskey="P"><<<
627 Previous</a></td>
628 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
629 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mailx.html" accesskey="N">Next
630 >>></a></td>
631 </tr>
632 </table>
633 <hr align="left" width="100%"></div>
634 </body>
635 </html>