| @@ -1,519 +1,519 @@ | | | @@ -1,519 +1,519 @@ |
1 | .\" $NetBSD: m4.1,v 1.28 2020/06/25 02:54:50 uwe Exp $ | | 1 | .\" $NetBSD: m4.1,v 1.29 2020/06/25 02:58:16 uwe Exp $ |
2 | .\" @(#) $OpenBSD: m4.1,v 1.56 2009/10/14 17:19:47 sthen Exp $ | | 2 | .\" @(#) $OpenBSD: m4.1,v 1.56 2009/10/14 17:19:47 sthen Exp $ |
3 | .\" | | 3 | .\" |
4 | .\" Copyright (c) 1989, 1993 | | 4 | .\" Copyright (c) 1989, 1993 |
5 | .\" The Regents of the University of California. All rights reserved. | | 5 | .\" The Regents of the University of California. All rights reserved. |
6 | .\" | | 6 | .\" |
7 | .\" This code is derived from software contributed to Berkeley by | | 7 | .\" This code is derived from software contributed to Berkeley by |
8 | .\" Ozan Yigit at York University. | | 8 | .\" Ozan Yigit at York University. |
9 | .\" | | 9 | .\" |
10 | .\" Redistribution and use in source and binary forms, with or without | | 10 | .\" Redistribution and use in source and binary forms, with or without |
11 | .\" modification, are permitted provided that the following conditions | | 11 | .\" modification, are permitted provided that the following conditions |
12 | .\" are met: | | 12 | .\" are met: |
13 | .\" 1. Redistributions of source code must retain the above copyright | | 13 | .\" 1. Redistributions of source code must retain the above copyright |
14 | .\" notice, this list of conditions and the following disclaimer. | | 14 | .\" notice, this list of conditions and the following disclaimer. |
15 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 15 | .\" 2. Redistributions in binary form must reproduce the above copyright |
16 | .\" notice, this list of conditions and the following disclaimer in the | | 16 | .\" notice, this list of conditions and the following disclaimer in the |
17 | .\" documentation and/or other materials provided with the distribution. | | 17 | .\" documentation and/or other materials provided with the distribution. |
18 | .\" 3. Neither the name of the University nor the names of its contributors | | 18 | .\" 3. Neither the name of the University nor the names of its contributors |
19 | .\" may be used to endorse or promote products derived from this software | | 19 | .\" may be used to endorse or promote products derived from this software |
20 | .\" without specific prior written permission. | | 20 | .\" without specific prior written permission. |
21 | .\" | | 21 | .\" |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | | 22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | | 25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
32 | .\" SUCH DAMAGE. | | 32 | .\" SUCH DAMAGE. |
33 | .\" | | 33 | .\" |
34 | .Dd January 16, 2015 | | 34 | .Dd June 25 16, 2020 |
35 | .Dt M4 1 | | 35 | .Dt M4 1 |
36 | .Os | | 36 | .Os |
37 | .Sh NAME | | 37 | .Sh NAME |
38 | .Nm m4 | | 38 | .Nm m4 |
39 | .Nd macro language processor | | 39 | .Nd macro language processor |
40 | .Sh SYNOPSIS | | 40 | .Sh SYNOPSIS |
41 | .Nm m4 | | 41 | .Nm m4 |
42 | .Op Fl EGgiPQsv | | 42 | .Op Fl EGgiPQsv |
43 | .Oo | | 43 | .Oo |
44 | .Sm off | | 44 | .Sm off |
45 | .Fl D Ar name Op No = Ar value | | 45 | .Fl D Ar name Op No = Ar value |
46 | .Sm on | | 46 | .Sm on |
47 | .Oc | | 47 | .Oc |
48 | .Op Fl d Ar flags | | 48 | .Op Fl d Ar flags |
49 | .Op Fl F Ar filename | | 49 | .Op Fl F Ar filename |
50 | .Op Fl I Ar dirname | | 50 | .Op Fl I Ar dirname |
51 | .Op Fl L Ar number | | 51 | .Op Fl L Ar number |
52 | .Op Fl o Ar filename | | 52 | .Op Fl o Ar filename |
53 | .Op Fl R Ar filename | | 53 | .Op Fl R Ar filename |
54 | .Op Fl t Ar macro | | 54 | .Op Fl t Ar macro |
55 | .Op Fl U Ns Ar name | | 55 | .Op Fl U Ns Ar name |
56 | .Op Ar | | 56 | .Op Ar |
57 | .Sh DESCRIPTION | | 57 | .Sh DESCRIPTION |
58 | The | | 58 | The |
59 | .Nm m4 | | 59 | .Nm m4 |
60 | utility is a macro processor that can be used as a front end to any | | 60 | utility is a macro processor that can be used as a front end to any |
61 | language (e.g., C, ratfor, fortran, lex, and yacc). | | 61 | language (e.g., C, ratfor, fortran, lex, and yacc). |
62 | If no input files are given, | | 62 | If no input files are given, |
63 | .Nm m4 | | 63 | .Nm m4 |
64 | reads from the standard input, | | 64 | reads from the standard input, |
65 | otherwise files specified on the command line are | | 65 | otherwise files specified on the command line are |
66 | processed in the given order. | | 66 | processed in the given order. |
67 | Input files can be regular files, files in the m4 include paths, or a | | 67 | Input files can be regular files, files in the m4 include paths, or a |
68 | single dash | | 68 | single dash |
69 | .Pq Sq - , | | 69 | .Pq Sq - , |
70 | denoting standard input. | | 70 | denoting standard input. |
71 | .Nm m4 | | 71 | .Nm m4 |
72 | writes | | 72 | writes |
73 | the processed text to the standard output, unless told otherwise. | | 73 | the processed text to the standard output, unless told otherwise. |
74 | .Pp | | 74 | .Pp |
75 | Macro calls have the form name(argument1[, argument2, ..., argumentN]). | | 75 | Macro calls have the form name(argument1[, argument2, ..., argumentN]). |
76 | .Pp | | 76 | .Pp |
77 | There cannot be any space following the macro name and the open | | 77 | There cannot be any space following the macro name and the open |
78 | parenthesis | | 78 | parenthesis |
79 | .Sq \&( . | | 79 | .Sq \&( . |
80 | If the macro name is not followed by an open | | 80 | If the macro name is not followed by an open |
81 | parenthesis it is processed with no arguments. | | 81 | parenthesis it is processed with no arguments. |
82 | .Pp | | 82 | .Pp |
83 | Macro names consist of a leading alphabetic or underscore | | 83 | Macro names consist of a leading alphabetic or underscore |
84 | possibly followed by alphanumeric or underscore characters, e.g., | | 84 | possibly followed by alphanumeric or underscore characters, e.g., |
85 | valid macro names match the pattern | | 85 | valid macro names match the pattern |
86 | .Dq [a-zA-Z_][a-zA-Z0-9_]* . | | 86 | .Dq [a-zA-Z_][a-zA-Z0-9_]* . |
87 | .Pp | | 87 | .Pp |
88 | In arguments to macros, leading unquoted space, tab, and newline | | 88 | In arguments to macros, leading unquoted space, tab, and newline |
89 | .Pq Sq \en | | 89 | .Pq Sq \en |
90 | characters are ignored. | | 90 | characters are ignored. |
91 | To quote strings, use left and right single quotes | | 91 | To quote strings, use left and right single quotes |
92 | .Po e.g.,\ \& | | 92 | .Po e.g.,\ \& |
93 | .Sq "\ this is a string with a leading space" | | 93 | .Sq "\ this is a string with a leading space" |
94 | .Pc . | | 94 | .Pc . |
95 | You can change the quote characters with the | | 95 | You can change the quote characters with the |
96 | .Ic changequote | | 96 | .Ic changequote |
97 | built-in macro. | | 97 | built-in macro. |
98 | .Pp | | 98 | .Pp |
99 | Most built-ins don't make any sense without arguments, and hence are not | | 99 | Most built-ins don't make any sense without arguments, and hence are not |
100 | recognized as special when not followed by an open parenthesis. | | 100 | recognized as special when not followed by an open parenthesis. |
101 | .Pp | | 101 | .Pp |
102 | The options are as follows: | | 102 | The options are as follows: |
103 | .Bl -tag -width Ds | | 103 | .Bl -tag -width Ds |
104 | .It Fl D , Fl Fl define Ar name Ns Op Pf = Ns Ar value | | 104 | .It Fl D , Fl Fl define Ar name Ns Op Pf = Ns Ar value |
105 | Define the symbol | | 105 | Define the symbol |
106 | .Ar name | | 106 | .Ar name |
107 | to have some value (or | | 107 | to have some value (or |
108 | .Dv NULL ) . | | 108 | .Dv NULL ) . |
109 | .It Fl d , Fl Fl debug Ar "flags" | | 109 | .It Fl d , Fl Fl debug Ar "flags" |
110 | Set trace flags. | | 110 | Set trace flags. |
111 | .Ar flags | | 111 | .Ar flags |
112 | may hold the following: | | 112 | may hold the following: |
113 | .Bl -tag -width Ds | | 113 | .Bl -tag -width Ds |
114 | .It Ar a | | 114 | .It Ar a |
115 | print macro arguments. | | 115 | print macro arguments. |
116 | .It Ar c | | 116 | .It Ar c |
117 | print macro expansion over several lines. | | 117 | print macro expansion over several lines. |
118 | .It Ar e | | 118 | .It Ar e |
119 | print result of macro expansion. | | 119 | print result of macro expansion. |
120 | .It Ar f | | 120 | .It Ar f |
121 | print filename location. | | 121 | print filename location. |
122 | .It Ar l | | 122 | .It Ar l |
123 | print line number. | | 123 | print line number. |
124 | .It Ar q | | 124 | .It Ar q |
125 | quote arguments and expansion with the current quotes. | | 125 | quote arguments and expansion with the current quotes. |
126 | .It Ar t | | 126 | .It Ar t |
127 | start with all macros traced. | | 127 | start with all macros traced. |
128 | .It Ar x | | 128 | .It Ar x |
129 | number macro expansions. | | 129 | number macro expansions. |
130 | .It Ar V | | 130 | .It Ar V |
131 | turn on all options. | | 131 | turn on all options. |
132 | .El | | 132 | .El |
133 | .Pp | | 133 | .Pp |
134 | By default, trace is set to | | 134 | By default, trace is set to |
135 | .Qq eq . | | 135 | .Qq eq . |
136 | .It Fl E , Fl Fl fatal-warnings | | 136 | .It Fl E , Fl Fl fatal-warnings |
137 | Warnings make | | 137 | Warnings make |
138 | .Nm | | 138 | .Nm |
139 | exit. | | 139 | exit. |
140 | .It Fl F , Fl Fl freeze-state Ar filename | | 140 | .It Fl F , Fl Fl freeze-state Ar filename |
141 | Save the input state to | | 141 | Save the input state to |
142 | .Ar filename . | | 142 | .Ar filename . |
143 | .It Fl G , Fl Fl traditional | | 143 | .It Fl G , Fl Fl traditional |
144 | Disable GNU-m4 extensions. | | 144 | Disable GNU-m4 extensions. |
145 | .It Fl g , Fl Fl gnu | | 145 | .It Fl g , Fl Fl gnu |
146 | Activate GNU-m4 compatibility mode. | | 146 | Activate GNU-m4 compatibility mode. |
147 | In this mode, translit handles simple character | | 147 | In this mode, translit handles simple character |
148 | ranges (e.g., a-z), regular expressions mimic emacs behavior, | | 148 | ranges (e.g., a-z), regular expressions mimic emacs behavior, |
149 | multiple m4wrap calls are handled as a stack, | | 149 | multiple m4wrap calls are handled as a stack, |
150 | the number of diversions is unlimited, | | 150 | the number of diversions is unlimited, |
151 | empty names for macro definitions are allowed, | | 151 | empty names for macro definitions are allowed, |
152 | and eval understands | | 152 | and eval understands |
153 | .Sq 0rbase:value | | 153 | .Sq 0rbase:value |
154 | numbers. | | 154 | numbers. |
155 | .It Fl Fl help | | 155 | .It Fl Fl help |
156 | Print help message and exit. | | 156 | Print help message and exit. |
157 | .It Fl I , Fl Fl include Ar "dirname" | | 157 | .It Fl I , Fl Fl include Ar "dirname" |
158 | Add directory | | 158 | Add directory |
159 | .Ar dirname | | 159 | .Ar dirname |
160 | to the include path. | | 160 | to the include path. |
161 | .It Fl i , Fl Fl interactive | | 161 | .It Fl i , Fl Fl interactive |
162 | Set unbuffered output, disable tty signals. | | 162 | Set unbuffered output, disable tty signals. |
163 | .It Fl L , Fl Fl nesting-limit | | 163 | .It Fl L , Fl Fl nesting-limit |
164 | Set the nesting limit in macro expansions. | | 164 | Set the nesting limit in macro expansions. |
165 | This is unimplemented and unlimited. | | 165 | This is unimplemented and unlimited. |
166 | .It Fl o , Fl Fl error-output Ar filename | | 166 | .It Fl o , Fl Fl error-output Ar filename |
167 | Send trace output to | | 167 | Send trace output to |
168 | .Ar filename . | | 168 | .Ar filename . |
169 | .It Fl P , Fl Fl prefix-builtins | | 169 | .It Fl P , Fl Fl prefix-builtins |
170 | Prefix all built-in macros with | | 170 | Prefix all built-in macros with |
171 | .Sq m4_ . | | 171 | .Sq m4_ . |
172 | For example, instead of writing | | 172 | For example, instead of writing |
173 | .Ic define , | | 173 | .Ic define , |
174 | use | | 174 | use |
175 | .Ic m4_define . | | 175 | .Ic m4_define . |
176 | .It Fl Q , Fl Fl quiet , Fl Fl silent | | 176 | .It Fl Q , Fl Fl quiet , Fl Fl silent |
177 | Don't print warnings. | | 177 | Don't print warnings. |
178 | .It Fl R , Fl Fl reload-state Ar filename | | 178 | .It Fl R , Fl Fl reload-state Ar filename |
179 | Reload a previously saved state from | | 179 | Reload a previously saved state from |
180 | .Ar filename . | | 180 | .Ar filename . |
181 | .It Fl s , Fl Fl synclines | | 181 | .It Fl s , Fl Fl synclines |
182 | Output line synchronization directives, suitable for | | 182 | Output line synchronization directives, suitable for |
183 | .Xr cpp 1 . | | 183 | .Xr cpp 1 . |
184 | .It Fl t , Fl Fl trace Ar macro | | 184 | .It Fl t , Fl Fl trace Ar macro |
185 | Turn tracing on for | | 185 | Turn tracing on for |
186 | .Ar macro . | | 186 | .Ar macro . |
187 | .It Fl U , Fl Fl undefine Ar "name" | | 187 | .It Fl U , Fl Fl undefine Ar "name" |
188 | Undefine the symbol | | 188 | Undefine the symbol |
189 | .Ar name . | | 189 | .Ar name . |
190 | .It Fl v , Fl Fl version | | 190 | .It Fl v , Fl Fl version |
191 | Print the version and exit. | | 191 | Print the version and exit. |
192 | .El | | 192 | .El |
193 | .Sh SYNTAX | | 193 | .Sh SYNTAX |
194 | .Nm m4 | | 194 | .Nm m4 |
195 | provides the following built-in macros. | | 195 | provides the following built-in macros. |
196 | They may be redefined, losing their original meaning. | | 196 | They may be redefined, losing their original meaning. |
197 | Return values are null unless otherwise stated. | | 197 | Return values are null unless otherwise stated. |
198 | .Bl -tag -width changequote | | 198 | .Bl -tag -width changequote |
199 | .It Fn builtin name | | 199 | .It Fn builtin name |
200 | Calls a built-in by its | | 200 | Calls a built-in by its |
201 | .Fa name , | | 201 | .Fa name , |
202 | overriding possible redefinitions. | | 202 | overriding possible redefinitions. |
203 | .It Fn changecom startcomment endcomment | | 203 | .It Fn changecom startcomment endcomment |
204 | Changes the start comment and end comment sequences. | | 204 | Changes the start comment and end comment sequences. |
205 | Comment sequences may be up to five characters long. | | 205 | Comment sequences may be up to five characters long. |
206 | The default values are the hash sign | | 206 | The default values are the hash sign |
207 | and the newline character. | | 207 | and the newline character. |
208 | .Bd -literal -offset indent | | 208 | .Bd -literal -offset indent |
209 | # This is a comment | | 209 | # This is a comment |
210 | .Ed | | 210 | .Ed |
211 | .Pp | | 211 | .Pp |
212 | With no arguments, comments are turned off. | | 212 | With no arguments, comments are turned off. |
213 | With one single argument, the end comment sequence is set | | 213 | With one single argument, the end comment sequence is set |
214 | to the newline character. | | 214 | to the newline character. |
215 | .It Fn changequote beginquote endquote | | 215 | .It Fn changequote beginquote endquote |
216 | Defines the open quote and close quote sequences. | | 216 | Defines the open quote and close quote sequences. |
217 | Quote sequences may be up to five characters long. | | 217 | Quote sequences may be up to five characters long. |
218 | The default values are the backquote character and the quote | | 218 | The default values are the backquote character and the quote |
219 | character. | | 219 | character. |
220 | .Bd -literal -offset indent | | 220 | .Bd -literal -offset indent |
221 | `Here is a quoted string' | | 221 | `Here is a quoted string' |
222 | .Ed | | 222 | .Ed |
223 | .Pp | | 223 | .Pp |
224 | With no arguments, the default quotes are restored. | | 224 | With no arguments, the default quotes are restored. |
225 | With one single argument, the close quote sequence is set | | 225 | With one single argument, the close quote sequence is set |
226 | to the newline character. | | 226 | to the newline character. |
227 | .It Fn decr arg | | 227 | .It Fn decr arg |
228 | Decrements the argument | | 228 | Decrements the argument |
229 | .Fa arg | | 229 | .Fa arg |
230 | by 1. | | 230 | by 1. |
231 | The argument | | 231 | The argument |
232 | .Fa arg | | 232 | .Fa arg |
233 | must be a valid numeric string. | | 233 | must be a valid numeric string. |
234 | .It Fn define name value | | 234 | .It Fn define name value |
235 | Define a new macro named by the first argument | | 235 | Define a new macro named by the first argument |
236 | .Fa name | | 236 | .Fa name |
237 | to have the | | 237 | to have the |
238 | value of the second argument | | 238 | value of the second argument |
239 | .Fa value . | | 239 | .Fa value . |
240 | Each occurrence of | | 240 | Each occurrence of |
241 | .Sq $n | | 241 | .Sq $n |
242 | (where | | 242 | (where |
243 | .Ar n | | 243 | .Ar n |
244 | is 0 through 9) is replaced by the | | 244 | is 0 through 9) is replaced by the |
245 | .Ar n Ns 'th | | 245 | .Ar n Ns 'th |
246 | argument. | | 246 | argument. |
247 | .Sq $0 | | 247 | .Sq $0 |
248 | is the name of the calling macro. | | 248 | is the name of the calling macro. |
249 | Undefined arguments are replaced by a null string. | | 249 | Undefined arguments are replaced by a null string. |
250 | .Sq $# | | 250 | .Sq $# |
251 | is replaced by the number of arguments; | | 251 | is replaced by the number of arguments; |
252 | .Sq $* | | 252 | .Sq $* |
253 | is replaced by all arguments comma separated; | | 253 | is replaced by all arguments comma separated; |
254 | .Sq $@ | | 254 | .Sq $@ |
255 | is the same as | | 255 | is the same as |
256 | .Sq $* | | 256 | .Sq $* |
257 | but all arguments are quoted against further expansion. | | 257 | but all arguments are quoted against further expansion. |
258 | .It Fn defn name ... | | 258 | .It Fn defn name ... |
259 | Returns the quoted definition for each argument. | | 259 | Returns the quoted definition for each argument. |
260 | This can be used to rename | | 260 | This can be used to rename |
261 | macro definitions (even for built-in macros). | | 261 | macro definitions (even for built-in macros). |
262 | .It Fn divert num | | 262 | .It Fn divert num |
263 | There are 10 output queues (numbered 0-9). | | 263 | There are 10 output queues (numbered 0-9). |
264 | At the end of processing | | 264 | At the end of processing |
265 | .Nm m4 | | 265 | .Nm m4 |
266 | concatenates all the queues in numerical order to produce the | | 266 | concatenates all the queues in numerical order to produce the |
267 | final output. | | 267 | final output. |
268 | Initially the output queue is 0. | | 268 | Initially the output queue is 0. |
269 | The divert | | 269 | The divert |
270 | macro allows you to select a new output queue (an invalid argument | | 270 | macro allows you to select a new output queue (an invalid argument |
271 | passed to divert causes output to be discarded). | | 271 | passed to divert causes output to be discarded). |
272 | .It Ic divnum | | 272 | .It Ic divnum |
273 | Returns the current output queue number. | | 273 | Returns the current output queue number. |
274 | .It Ic dnl | | 274 | .It Ic dnl |
275 | Discard input characters up to and including the next newline. | | 275 | Discard input characters up to and including the next newline. |
276 | .It Fn dumpdef name ... | | 276 | .It Fn dumpdef name ... |
277 | Prints the names and definitions for the named items, or for everything | | 277 | Prints the names and definitions for the named items, or for everything |
278 | if no arguments are passed. | | 278 | if no arguments are passed. |
279 | .It Fn errprint msg | | 279 | .It Fn errprint msg |
280 | Prints the first argument on the standard error output stream. | | 280 | Prints the first argument on the standard error output stream. |
281 | .It Fn esyscmd cmd | | 281 | .It Fn esyscmd cmd |
282 | Passes its first argument to a shell and returns the shell's standard output. | | 282 | Passes its first argument to a shell and returns the shell's standard output. |
283 | Note that the shell shares its standard input and standard error with | | 283 | Note that the shell shares its standard input and standard error with |
284 | .Nm m4 . | | 284 | .Nm m4 . |
285 | .It Fn eval expr[,radix[,minimum]] | | 285 | .It Fn eval expr[,radix[,minimum]] |
286 | Computes the first argument as an arithmetic expression using 32-bit | | 286 | Computes the first argument as an arithmetic expression using 32-bit |
287 | arithmetic. | | 287 | arithmetic. |
288 | Operators are the standard C ternary, arithmetic, logical, | | 288 | Operators are the standard C ternary, arithmetic, logical, |
289 | shift, relational, bitwise, and parentheses operators. | | 289 | shift, relational, bitwise, and parentheses operators. |
290 | You can specify | | 290 | You can specify |
291 | octal, decimal, and hexadecimal numbers as in C. | | 291 | octal, decimal, and hexadecimal numbers as in C. |
292 | The optional second argument | | 292 | The optional second argument |
293 | .Fa radix | | 293 | .Fa radix |
294 | specifies the radix for the result and the optional third argument | | 294 | specifies the radix for the result and the optional third argument |
295 | .Fa minimum | | 295 | .Fa minimum |
296 | specifies the minimum number of digits in the result. | | 296 | specifies the minimum number of digits in the result. |
297 | .It Fn expr expr | | 297 | .It Fn expr expr |
298 | This is an alias for | | 298 | This is an alias for |
299 | .Ic eval . | | 299 | .Ic eval . |
300 | .It Fn format formatstring arg1 ... | | 300 | .It Fn format formatstring arg1 ... |
301 | Returns | | 301 | Returns |
302 | .Fa formatstring | | 302 | .Fa formatstring |
303 | with escape sequences substituted with | | 303 | with escape sequences substituted with |
304 | .Fa arg1 | | 304 | .Fa arg1 |
305 | and following arguments, in a way similar to | | 305 | and following arguments, in a way similar to |
306 | .Xr printf 3 . | | 306 | .Xr printf 3 . |
307 | This built-in is only available in GNU-m4 compatibility mode, and the only | | 307 | This built-in is only available in GNU-m4 compatibility mode, and the only |
308 | parameters implemented are there for autoconf compatibility: | | 308 | parameters implemented are there for autoconf compatibility: |
309 | left-padding flag, an optional field width, a maximum field width, | | 309 | left-padding flag, an optional field width, a maximum field width, |
310 | *-specified field widths, and the %s and %c data type. | | 310 | *-specified field widths, and the %s and %c data type. |
311 | .It Fn ifdef name yes no | | 311 | .It Fn ifdef name yes no |
312 | If the macro named by the first argument is defined then return the second | | 312 | If the macro named by the first argument is defined then return the second |
313 | argument, otherwise the third. | | 313 | argument, otherwise the third. |
314 | If there is no third argument, the value is | | 314 | If there is no third argument, the value is |
315 | .Dv NULL . | | 315 | .Dv NULL . |
316 | The word | | 316 | The word |
317 | .Qq unix | | 317 | .Qq unix |
318 | is predefined. | | 318 | is predefined. |
319 | .It Fn ifelse a b yes ... | | 319 | .It Fn ifelse a b yes ... |
320 | If the first argument | | 320 | If the first argument |
321 | .Fa a | | 321 | .Fa a |
322 | matches the second argument | | 322 | matches the second argument |
323 | .Fa b | | 323 | .Fa b |
324 | then | | 324 | then |
325 | .Fn ifelse | | 325 | .Fn ifelse |
326 | returns | | 326 | returns |
327 | the third argument | | 327 | the third argument |
328 | .Fa yes . | | 328 | .Fa yes . |
329 | If the match fails the three arguments are | | 329 | If the match fails the three arguments are |
330 | discarded and the next three arguments are used until there is | | 330 | discarded and the next three arguments are used until there is |
331 | zero or one arguments left, either this last argument or | | 331 | zero or one arguments left, either this last argument or |
332 | .Dv NULL | | 332 | .Dv NULL |
333 | is returned if no other matches were found. | | 333 | is returned if no other matches were found. |
334 | .It Fn include name | | 334 | .It Fn include name |
335 | Returns the contents of the file specified in the first argument. | | 335 | Returns the contents of the file specified in the first argument. |
336 | If the file is not found as is, look through the include path: | | 336 | If the file is not found as is, look through the include path: |
337 | first the directories specified with | | 337 | first the directories specified with |
338 | .Fl I | | 338 | .Fl I |
339 | on the command line, then the environment variable | | 339 | on the command line, then the environment variable |
340 | .Ev M4PATH , | | 340 | .Ev M4PATH , |
341 | as a colon-separated list of directories. | | 341 | as a colon-separated list of directories. |
342 | Include aborts with an error message if the file cannot be included. | | 342 | Include aborts with an error message if the file cannot be included. |
343 | .It Fn incr arg | | 343 | .It Fn incr arg |
344 | Increments the argument by 1. | | 344 | Increments the argument by 1. |
345 | The argument must be a valid numeric string. | | 345 | The argument must be a valid numeric string. |
346 | .It Fn index string substring | | 346 | .It Fn index string substring |
347 | Returns the index of the second argument in the first argument (e.g., | | 347 | Returns the index of the second argument in the first argument (e.g., |
348 | .Ic index(the quick brown fox jumped, fox) | | 348 | .Ic index(the quick brown fox jumped, fox) |
349 | returns 16). | | 349 | returns 16). |
350 | If the second | | 350 | If the second |
351 | argument is not found index returns \-1. | | 351 | argument is not found index returns \-1. |
352 | .It Fn indir macro arg1 ... | | 352 | .It Fn indir macro arg1 ... |
353 | Indirectly calls the macro whose name is passed as the first argument, | | 353 | Indirectly calls the macro whose name is passed as the first argument, |
354 | with the remaining arguments passed as first, ... arguments. | | 354 | with the remaining arguments passed as first, ... arguments. |
355 | .It Fn len arg | | 355 | .It Fn len arg |
356 | Returns the number of characters in the first argument. | | 356 | Returns the number of characters in the first argument. |
357 | Extra arguments | | 357 | Extra arguments |
358 | are ignored. | | 358 | are ignored. |
359 | .It Fn m4exit code | | 359 | .It Fn m4exit code |
360 | Immediately exits with the return value specified by the first argument, | | 360 | Immediately exits with the return value specified by the first argument, |
361 | 0 if none. | | 361 | 0 if none. |
362 | .It Fn m4wrap todo | | 362 | .It Fn m4wrap todo |
363 | Allows you to define what happens at the final | | 363 | Allows you to define what happens at the final |
364 | .Dv EOF , | | 364 | .Dv EOF , |
365 | usually for cleanup purposes (e.g., | | 365 | usually for cleanup purposes (e.g., |
366 | .Ic m4wrap("cleanup(tempfile)") | | 366 | .Ic m4wrap("cleanup(tempfile)") |
367 | causes the macro cleanup to be | | 367 | causes the macro cleanup to be |
368 | invoked after all other processing is done). | | 368 | invoked after all other processing is done). |
369 | .Pp | | 369 | .Pp |
370 | Multiple calls to | | 370 | Multiple calls to |
371 | .Fn m4wrap | | 371 | .Fn m4wrap |
372 | get inserted in sequence at the final | | 372 | get inserted in sequence at the final |
373 | .Dv EOF . | | 373 | .Dv EOF . |
374 | .It Fn maketemp template | | 374 | .It Fn maketemp template |
375 | Invokes | | 375 | Invokes |
376 | .Xr mkstemp 3 | | 376 | .Xr mkstemp 3 |
377 | on the first argument, and returns the modified string. | | 377 | on the first argument, and returns the modified string. |
378 | This can be used to create unique | | 378 | This can be used to create unique |
379 | temporary file names. | | 379 | temporary file names. |
380 | .It Fn paste file | | 380 | .It Fn paste file |
381 | Includes the contents of the file specified by the first argument without | | 381 | Includes the contents of the file specified by the first argument without |
382 | any macro processing. | | 382 | any macro processing. |
383 | Aborts with an error message if the file cannot be | | 383 | Aborts with an error message if the file cannot be |
384 | included. | | 384 | included. |
385 | .It Fn patsubst string regexp replacement | | 385 | .It Fn patsubst string regexp replacement |
386 | Substitutes a regular expression in a string with a replacement string. | | 386 | Substitutes a regular expression in a string with a replacement string. |
387 | Usual substitution patterns apply: an ampersand | | 387 | Usual substitution patterns apply: an ampersand |
388 | .Pq Sq \&& | | 388 | .Pq Sq \&& |
389 | is replaced by the string matching the regular expression. | | 389 | is replaced by the string matching the regular expression. |
390 | The string | | 390 | The string |
391 | .Sq \e# , | | 391 | .Sq \e# , |
392 | where | | 392 | where |
393 | .Sq # | | 393 | .Sq # |
394 | is a digit, is replaced by the corresponding back-reference. | | 394 | is a digit, is replaced by the corresponding back-reference. |
395 | .It Fn popdef arg ... | | 395 | .It Fn popdef arg ... |
396 | Restores the | | 396 | Restores the |
397 | .Ic pushdef Ns ed | | 397 | .Ic pushdef Ns ed |
398 | definition for each argument. | | 398 | definition for each argument. |
399 | .It Fn pushdef macro def | | 399 | .It Fn pushdef macro def |
400 | Takes the same arguments as | | 400 | Takes the same arguments as |
401 | .Ic define , | | 401 | .Ic define , |
402 | but it saves the definition on a | | 402 | but it saves the definition on a |
403 | stack for later retrieval by | | 403 | stack for later retrieval by |
404 | .Fn popdef . | | 404 | .Fn popdef . |
405 | .It Fn regexp string regexp replacement | | 405 | .It Fn regexp string regexp replacement |
406 | Finds a regular expression in a string. | | 406 | Finds a regular expression in a string. |
407 | If no further arguments are given, | | 407 | If no further arguments are given, |
408 | it returns the first match position or \-1 if no match. | | 408 | it returns the first match position or \-1 if no match. |
409 | If a third argument | | 409 | If a third argument |
410 | is provided, it returns the replacement string, with sub-patterns replaced. | | 410 | is provided, it returns the replacement string, with sub-patterns replaced. |
411 | .It Fn shift arg1 ... | | 411 | .It Fn shift arg1 ... |
412 | Returns all but the first argument, the remaining arguments are | | 412 | Returns all but the first argument, the remaining arguments are |
413 | quoted and pushed back with commas in between. | | 413 | quoted and pushed back with commas in between. |
414 | The quoting | | 414 | The quoting |
415 | nullifies the effect of the extra scan that will subsequently be | | 415 | nullifies the effect of the extra scan that will subsequently be |
416 | performed. | | 416 | performed. |
417 | .It Fn sinclude file | | 417 | .It Fn sinclude file |
418 | Similar to | | 418 | Similar to |
419 | .Ic include , | | 419 | .Ic include , |
420 | except it ignores any errors. | | 420 | except it ignores any errors. |
421 | .It Fn spaste file | | 421 | .It Fn spaste file |
422 | Similar to | | 422 | Similar to |
423 | .Fn paste , | | 423 | .Fn paste , |
424 | except it ignores any errors. | | 424 | except it ignores any errors. |
425 | .It Fn substr string offset length | | 425 | .It Fn substr string offset length |
426 | Returns a substring of the first argument starting at the offset specified | | 426 | Returns a substring of the first argument starting at the offset specified |
427 | by the second argument and the length specified by the third argument. | | 427 | by the second argument and the length specified by the third argument. |
428 | If no third argument is present it returns the rest of the string. | | 428 | If no third argument is present it returns the rest of the string. |
429 | .It Fn syscmd cmd | | 429 | .It Fn syscmd cmd |
430 | Passes the first argument to the shell. | | 430 | Passes the first argument to the shell. |
431 | Nothing is returned. | | 431 | Nothing is returned. |
432 | .It Ic sysval | | 432 | .It Ic sysval |
433 | Returns the return value from the last | | 433 | Returns the return value from the last |
434 | .Ic syscmd . | | 434 | .Ic syscmd . |
435 | .It Fn traceon arg ... | | 435 | .It Fn traceon arg ... |
436 | Enables tracing of macro expansions for the given arguments, or for all | | 436 | Enables tracing of macro expansions for the given arguments, or for all |
437 | macros if no argument is given. | | 437 | macros if no argument is given. |
438 | .It Fn traceoff arg ... | | 438 | .It Fn traceoff arg ... |
439 | Disables tracing of macro expansions for the given arguments, or for all | | 439 | Disables tracing of macro expansions for the given arguments, or for all |
440 | macros if no argument is given. | | 440 | macros if no argument is given. |
441 | .It Fn translit string mapfrom mapto | | 441 | .It Fn translit string mapfrom mapto |
442 | Transliterate the characters in the first argument from the set | | 442 | Transliterate the characters in the first argument from the set |
443 | given by the second argument to the set given by the third. | | 443 | given by the second argument to the set given by the third. |
444 | You cannot use | | 444 | You cannot use |
445 | .Xr tr 1 | | 445 | .Xr tr 1 |
446 | style abbreviations. | | 446 | style abbreviations. |
447 | .It Fn undefine name1 ... | | 447 | .It Fn undefine name1 ... |
448 | Removes the definition for the macros specified by its arguments. | | 448 | Removes the definition for the macros specified by its arguments. |
449 | .It Fn undivert arg ... | | 449 | .It Fn undivert arg ... |
450 | Flushes the named output queues (or all queues if no arguments). | | 450 | Flushes the named output queues (or all queues if no arguments). |
451 | .It Ic unix | | 451 | .It Ic unix |
452 | A pre-defined macro for testing the OS platform. | | 452 | A pre-defined macro for testing the OS platform. |
453 | .It Ic __line__ | | 453 | .It Ic __line__ |
454 | Returns the current file's line number. | | 454 | Returns the current file's line number. |
455 | .It Ic __file__ | | 455 | .It Ic __file__ |
456 | Returns the current file's name. | | 456 | Returns the current file's name. |
457 | .El | | 457 | .El |
458 | .Sh STANDARDS | | 458 | .Sh STANDARDS |
459 | The | | 459 | The |
460 | .Nm | | 460 | .Nm |
461 | utility is compliant with the | | 461 | utility is compliant with the |
462 | .St -p1003.1-2008 | | 462 | .St -p1003.1-2008 |
463 | specification. | | 463 | specification. |
464 | .Pp | | 464 | .Pp |
465 | The flags | | 465 | The flags |
466 | .Op Fl dgIot | | 466 | .Op Fl dgIot |
467 | and the macros | | 467 | and the macros |
468 | .Ic builtin , | | 468 | .Ic builtin , |
469 | .Ic esyscmd , | | 469 | .Ic esyscmd , |
470 | .Ic expr , | | 470 | .Ic expr , |
471 | .Ic format , | | 471 | .Ic format , |
472 | .Ic indir , | | 472 | .Ic indir , |
473 | .Ic paste , | | 473 | .Ic paste , |
474 | .Ic patsubst , | | 474 | .Ic patsubst , |
475 | .Ic regexp , | | 475 | .Ic regexp , |
476 | .Ic spaste , | | 476 | .Ic spaste , |
477 | .Ic unix , | | 477 | .Ic unix , |
478 | .Ic __line__ , | | 478 | .Ic __line__ , |
479 | and | | 479 | and |
480 | .Ic __file__ | | 480 | .Ic __file__ |
481 | are extensions to that specification. | | 481 | are extensions to that specification. |
482 | .Pp | | 482 | .Pp |
483 | The output format of tracing and of | | 483 | The output format of tracing and of |
484 | .Ic dumpdef | | 484 | .Ic dumpdef |
485 | are not specified in any standard, | | 485 | are not specified in any standard, |
486 | are likely to change and should not be relied upon. | | 486 | are likely to change and should not be relied upon. |
487 | The current format of tracing is closely modelled on | | 487 | The current format of tracing is closely modelled on |
488 | .Nm gnu-m4 , | | 488 | .Nm gnu-m4 , |
489 | to allow | | 489 | to allow |
490 | .Nm autoconf | | 490 | .Nm autoconf |
491 | to work. | | 491 | to work. |
492 | .Pp | | 492 | .Pp |
493 | The built-ins | | 493 | The built-ins |
494 | .Ic pushdef | | 494 | .Ic pushdef |
495 | and | | 495 | and |
496 | .Ic popdef | | 496 | .Ic popdef |
497 | handle macro definitions as a stack. | | 497 | handle macro definitions as a stack. |
498 | However, | | 498 | However, |
499 | .Ic define | | 499 | .Ic define |
500 | interacts with the stack in an undefined way. | | 500 | interacts with the stack in an undefined way. |
501 | In this implementation, | | 501 | In this implementation, |
502 | .Ic define | | 502 | .Ic define |
503 | replaces the top-most definition only. | | 503 | replaces the top-most definition only. |
504 | Other implementations may erase all definitions on the stack instead. | | 504 | Other implementations may erase all definitions on the stack instead. |
505 | .Pp | | 505 | .Pp |
506 | All built-ins do expand without arguments in many other | | 506 | All built-ins do expand without arguments in many other |
507 | .Nm m4 . | | 507 | .Nm m4 . |
508 | .Pp | | 508 | .Pp |
509 | Many other | | 509 | Many other |
510 | .Nm | | 510 | .Nm |
511 | have dire size limitations with respect to buffer sizes. | | 511 | have dire size limitations with respect to buffer sizes. |
512 | .Sh AUTHORS | | 512 | .Sh AUTHORS |
513 | .An -nosplit | | 513 | .An -nosplit |
514 | .An Ozan Yigit Aq Mt oz@sis.yorku.ca | | 514 | .An Ozan Yigit Aq Mt oz@sis.yorku.ca |
515 | and | | 515 | and |
516 | .An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU . | | 516 | .An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU . |
517 | .Pp | | 517 | .Pp |
518 | GNU-m4 compatibility extensions by | | 518 | GNU-m4 compatibility extensions by |
519 | .An Marc Espie Aq Mt espie@cvs.openbsd.org . | | 519 | .An Marc Espie Aq Mt espie@cvs.openbsd.org . |