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