m4(1) - osol9

1m4(1)                            User Commands                           m4(1)
2
3
4

NAME

6       m4 - macro processor
7

SYNOPSIS

9       /usr/bin/m4 [-e] [-s] [-B int] [-H int] [-S int]
10            [-T int] [-Dname [=val]] ... [-U name] ... [file]...
11
12
13       /usr/xpg4/bin/m4 [-e] [-s] [-B int] [-H int] [-S int]
14            [-T int] [-Dname [...=val]] [-U name] ... [file]...
15
16

DESCRIPTION

18       The  m4  utility  is  a  macro processor intended as a front end for C,
19       assembler, and other languages. Each of the argument files is processed
20       in  order. If there are no files, or if a file is −, the standard input
21       is read. The processed text is written on the standard output. Note: m4
22       cannot include more than nine nested files and writes a diagnostic mes‐
23       sage if that number is exceeded.
24
25   Macro Syntax
26       Macro calls have the form:
27
28         name(arg1,arg2, ..., argn)
29
30
31
32
33       The open parenthesis character, (, must immediately follow the name  of
34       the macro. If the name of a defined macro is not followed by a (, it is
35       deemed to be a call of that macro with no  arguments.  Potential  macro
36       names  consist of alphanumeric characters and underscore (_), where the
37       first character is not a digit.
38
39
40       Leading unquoted blanks, TABs, and NEWLINEs are ignored while  collect‐
41       ing  arguments. Left and right single quotes are used to quote strings.
42       The value of a quoted string is the string stripped of the quotes.
43
44   Macro Processing
45       When a macro name is recognized, its arguments are collected by search‐
46       ing  for  a matching right parenthesis. If fewer arguments are supplied
47       than are in the macro definition, the trailing arguments are  taken  to
48       be  NULL.  Macro  evaluation proceeds normally during the collection of
49       the arguments, and any commas or right parentheses that happen to  turn
50       up  within  the value of a nested call are as effective as those in the
51       original input text. After argument collection, the value of the  macro
52       is pushed back onto the input stream and rescanned.
53

OPTIONS

55       The options and their effects are as follows:
56
57       -Bint    Changes the size of the push-back and argument collection buf‐
58                fers from the default of 4,096.
59
60
61       -e       Operates interactively. Interrupts are ignored and the  output
62                is unbuffered.
63
64
65       -Hint    Changes  the  size  of  the  symbol  table hash array from the
66                default of 199. The size should be prime.
67
68
69       -s       Enables line sync output for the C preprocessor (#line ...)
70
71
72       -Sint    Changes the size  of  the  call  stack  from  the  default  of
73                100slots.  Macros  take  three  slots, and non-macro arguments
74                take one.
75
76
77       -Tint    Changes the size of the  token  buffer  from  the  default  of
78                512bytes.
79
80
81
82       To  be effective, the above flags must appear before any file names and
83       before any -D or -U flags:
84
85       -D name[=val]    Defines name to val or to NULL in val's absence.
86
87
88       -Uname           Undefines name.
89
90

OPERANDS

92       The following operand is supported:
93
94       file    A path name of a text file to  be  processed.  If  no  file  is
95               given, or if it is −, the standard input is read.
96
97

USAGE

99       The  m4  utility  makes  available the following built-in macros. These
100       macros can be redefined, but once this is done the original meaning  is
101       lost. Their values are NULL unless otherwise stated.
102
103       changequote    Change  quote symbols to the first and second arguments.
104                      The symbols can be up to five characters  long.  change‐
105                      quote  without  arguments  restores  the original values
106                      (that is, `').
107
108
109       changecom      Change left and right comment markers from the default #
110                      and NEWLINE. With no arguments, the comment mechanism is
111                      effectively disabled. With one argument, the left marker
112                      becomes  the  argument and the right marker becomes NEW‐
113                      LINE. With two arguments,  both  markers  are  affected.
114                      Comment markers can be up to five characters long.
115
116
117       decr           Returns the value of its argument decremented by 1.
118
119
120       define         The  second  argument  is  installed as the value of the
121                      macro whose name is the first argument. Each  occurrence
122                      of  $n  in  the replacement text, where n is a digit, is
123                      replaced by the n-th argument. Argument 0 is the name of
124                      the  macro;  missing  arguments are replaced by the null
125                      string; $# is replaced by the number of arguments; $* is
126                      replaced  by  a  list  of all the arguments separated by
127                      commas; $@ is like $*, but each argument is quoted (with
128                      the current quotes).
129
130
131       defn           Returns  the quoted definition of its argument(s). It is
132                      useful for renaming macros, especially built-ins.
133
134
135       divert         m4 maintains 10 output streams, numbered 0-9. The  final
136                      output  is the concatenation of the streams in numerical
137                      order. Initially stream 0 is  the  current  stream.  The
138                      divert  macro  changes  the current output stream to its
139                      (digit-string) argument. Output  diverted  to  a  stream
140                      other than 0 through 9 is discarded.
141
142
143       divnum         Returns the value of the current output stream.
144
145
146       dnl            Reads  and  discards  characters up to and including the
147                      next NEWLINE.
148
149
150       dumpdef        Prints current names  and  definitions,  for  the  named
151                      items, or for all if no arguments are given.
152
153
154       errprint       Prints its argument on the diagnostic output file.
155
156
157       ifdef          If  the first argument is defined, the value is the sec‐
158                      ond argument, otherwise the third. If there is no  third
159                      argument,  the  value  is  NULL. The word unix is prede‐
160                      fined.
161
162
163       ifelse         This macro has three or more  arguments.  If  the  first
164                      argument  is  the  same  string  as the second, then the
165                      value is the third argument. If not, and  if  there  are
166                      more  than  four arguments, the process is repeated with
167                      arguments 4, 5, 6 and 7. Otherwise, the value is  either
168                      the fourth string, or, if it is not present, NULL.
169
170
171       include        Returns the contents of the file named in the argument.
172
173
174       incr           Returns  the value of its argument incremented by 1. The
175                      value of the argument is calculated by  interpreting  an
176                      initial digit-string as a decimal number.
177
178
179       index          Returns  the  position  in  its first argument where the
180                      second argument begins (zero origin), or −1 if the  sec‐
181                      ond argument does not occur.
182
183
184       len            Returns the number of characters in its argument.
185
186
187       m4exit         This macro causes immediate exit from m4. Argument 1, if
188                      given, is the exit code; the default is 0.
189
190
191       m4wrap         Argument  1  is  pushed  back  at  final  EOF.  Example:
192                      m4wrap(`cleanup()')
193
194
195       maketemp       Fills in a string of "X" characters in its argument with
196                      the current process ID.
197
198
199       popdef         Removes current definition of its argument(s),  exposing
200                      the previous one, if any.
201
202
203       pushdef        Like define, but saves any previous definition.
204
205
206       shift          Returns  all but its first argument. The other arguments
207                      are quoted and pushed back with commas in  between.  The
208                      quoting  nullifies  the effect of the extra scan that is
209                      subsequently be performed.
210
211
212       sinclude       This macro is identical to include, except that it  says
213                      nothing if the file is inaccessible.
214
215
216       substr         Returns  a  substring  of its first argument. The second
217                      argument is a zero origin  number  selecting  the  first
218                      character;  the  third  argument indicates the length of
219                      the substring. A missing third argument is taken  to  be
220                      large enough to extend to the end of the first string.
221
222
223       syscmd         This macro executes the command given in the first argu‐
224                      ment. No value is returned.
225
226
227       sysval         This macro is the return code  from  the  last  call  to
228                      syscmd.
229
230
231       translit       Transliterates the characters in its first argument from
232                      the set given by the second argument to the set given by
233                      the third. No abbreviations are permitted.
234
235
236       traceon        This  macro  with no arguments, turns on tracing for all
237                      macros (including built-ins). Otherwise, turns on  trac‐
238                      ing for named macros.
239
240
241       traceoff       Turns off trace globally and for any macros specified.
242
243
244       undefine       Removes  the  definition of the macro named in its argu‐
245                      ment.
246
247
248       undivert       This macro causes immediate output of text  from  diver‐
249                      sions  named as arguments, or all diversions if no argu‐
250                      ment. Text can be  undiverted  into  another  diversion.
251                      Undiverting discards the diverted text.
252
253
254   /usr/bin/m4
255       eval    Evaluates  its  argument  as  an  arithmetic  expression, using
256               32-bit signed-integer arithmetic. The following  operators  are
257               supported:  parentheses, unary -, unary +, !, ~, *, /, %, +, -,
258               relationals, bitwise &, |, &&, and ||. Octal  and  hex  numbers
259               can  be  specified  as  in C. The second argument specifies the
260               radix for the result; the default is  10.  The  third  argument
261               can  be  used  to  specify  the minimum number of digits in the
262               result.
263
264
265   /usr/xpg4/bin/m4
266       eval    Evaluates its argument  as  an  arithmetic  expression,   using
267               32-bit  signed-integer  arithmetic. The following operators are
268               supported: parentheses, unary -, unary +, !, ~, *, /, %, +,  -,
269               <<,  >>,  relationals, bitwise &, |, &&, and ||. Precedence and
270               associativity are as in C. Octal and hex numbers  can  also  be
271               specified  as in C. The second argument specifies the radix for
272               the result; the default is 10. The third argument can  be  used
273               to specify the minimum number of digits in the result.
274
275

EXAMPLES

277       Example 1 Examples of m4 files
278
279
280       If the file m4src contains the lines:
281
282
283         The value of `VER' is "VER".
284                 ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
285                 ifelse(VER, 1, ``VER'' is `VER'.)
286                 ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
287                 end
288
289
290
291
292       then the command:
293
294
295         m4 m4src
296
297
298
299
300       or the command:
301
302
303         m4 -U VER m4src
304
305
306
307
308       produces the output:
309
310
311         The value of VER is "VER".
312                 VER is not defined.
313
314                 VER is not 2.
315                 end
316
317
318
319
320       The command:
321
322
323         m4 -D VER m4src
324
325
326
327
328       produces the output:
329
330
331         The value of VER is "".
332                 VER is defined to be .
333
334                 VER is not 2.
335                 end
336
337
338
339
340       The command:
341
342
343         m4 -D VER=1 m4src
344
345
346
347
348       produces the output:
349
350
351         The value of VER is "1".
352                VER is defined to be 1.
353                VER is 1.
354                VER is not 2.
355                end
356
357
358
359
360       The command:
361
362
363         m4 -D VER=2 m4src
364
365
366
367
368       produces the output:
369
370
371         The value of VER is "2".
372                 VER is defined to be 2.
373
374                 VER is 2.
375                 end
376
377
378

ENVIRONMENT VARIABLES

380       See  environ(5) for descriptions of the following environment variables
381       that affect the execution of m4: LANG, LC_ALL,  LC_CTYPE,  LC_MESSAGES,
382       and NLSPATH.
383

EXIT STATUS

385       The following exit values are returned:
386
387       0     Successful completion.
388
389
390       >0    An error occurred
391
392
393
394       If  the  m4exit  macro  is used, the exit value can be specified by the
395       input file.
396

ATTRIBUTES

398       See attributes(5) for descriptions of the following attributes:
399
400   /usr/bin/m4
401       ┌─────────────────────────────┬─────────────────────────────┐
402       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
403       ├─────────────────────────────┼─────────────────────────────┤
404       │Availability                 │SUNWcsu                      │
405       └─────────────────────────────┴─────────────────────────────┘
406
407   /usr/xpg4/bin/m4
408       ┌─────────────────────────────┬─────────────────────────────┐
409       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
410       ├─────────────────────────────┼─────────────────────────────┤
411       │Availability                 │SUNWxcu4                     │
412       ├─────────────────────────────┼─────────────────────────────┤
413       │Interface Stability          │Standard                     │
414       └─────────────────────────────┴─────────────────────────────┘
415