| blob | c7ae9e1bde03860d4d3964ec0626a6d8571443b9 |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .TH M4 1 "Jul 3, 2007"
11 .SH NAME
12 m4 \- macro processor
13 .SH SYNOPSIS
14 .LP
15 .nf
16 \fB/usr/bin/m4\fR [\fB-e\fR] [\fB-s\fR] [\fB-B\fR \fIint\fR] [\fB-H\fR \fIint\fR] [\fB-S\fR \fIint\fR]
17 [\fB-T\fR \fIint\fR] [\fB-D\fR\fIname\fR [\fI=val\fR]] ... [\fB-U\fR \fIname\fR] ... [\fIfile\fR]...
18 .fi
20 .LP
21 .nf
22 \fB/usr/xpg4/bin/m4\fR [\fB-e\fR] [\fB-s\fR] [\fB-B\fR \fIint\fR] [\fB-H\fR \fIint\fR] [\fB-S\fR \fIint\fR]
23 [\fB-T\fR \fIint\fR] [\fB-D\fR\fIname\fR [...\fI=val\fR]] [\fB-U\fR \fIname\fR] ... [\fIfile\fR]...
24 .fi
26 .SH DESCRIPTION
27 .sp
28 .LP
29 The \fBm4\fR utility is a macro processor intended as a front end for C,
30 assembler, and other languages. Each of the argument files is processed in
31 order. If there are no files, or if a file is \fB\(mi\fR, the standard input is
32 read. The processed text is written on the standard output. \fBNote:\fR
33 \fBm4\fR cannot include more than nine nested files and writes a diagnostic
34 message if that number is exceeded.
35 .SS "Macro Syntax"
36 .sp
37 .LP
38 Macro calls have the form:
39 .sp
40 .in +2
41 .nf
42 \fIname\fR(\fIarg1\fR,\fIarg2\fR, ..., \fIargn\fR)
43 .fi
44 .in -2
45 .sp
47 .sp
48 .LP
49 The open parenthesis character, \fB(\fR, must immediately follow the name of
50 the macro. If the name of a defined macro is not followed by a \fB(\fR, it is
51 deemed to be a call of that macro with no arguments. Potential macro names
52 consist of alphanumeric characters and underscore (\fB_\fR), where the first
53 character is not a digit.
54 .sp
55 .LP
56 Leading unquoted blanks, TABs, and \fBNEWLINE\fRs are ignored while collecting
57 arguments. Left and right single quotes are used to quote strings. The value of
58 a quoted string is the string stripped of the quotes.
59 .SS "Macro Processing"
60 .sp
61 .LP
62 When a macro name is recognized, its arguments are collected by searching for a
63 matching right parenthesis. If fewer arguments are supplied than are in the
64 macro definition, the trailing arguments are taken to be \fINULL\fR. Macro
65 evaluation proceeds normally during the collection of the arguments, and any
66 commas or right parentheses that happen to turn up within the value of a nested
67 call are as effective as those in the original input text. After argument
68 collection, the value of the macro is pushed back onto the input stream and
69 rescanned.
70 .SH OPTIONS
71 .sp
72 .LP
73 The options and their effects are as follows:
74 .sp
75 .ne 2
76 .na
77 \fB\fB-B\fR\fIint\fR\fR
78 .ad
79 .RS 9n
80 Changes the size of the push-back and argument collection buffers from the
81 default of \fB4,096\fR.
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fB-e\fR\fR
88 .ad
89 .RS 9n
90 Operates interactively. Interrupts are ignored and the output is unbuffered.
91 .RE
93 .sp
94 .ne 2
95 .na
96 \fB\fB-H\fR\fIint\fR\fR
97 .ad
98 .RS 9n
99 Changes the size of the symbol table hash array from the default of \fB199\fR.
100 The size should be prime.
101 .RE
103 .sp
104 .ne 2
105 .na
106 \fB\fB-s\fR\fR
107 .ad
108 .RS 9n
109 Enables line sync output for the C preprocessor (\fB#\fRline .\|.\|.\|)
110 .RE
112 .sp
113 .ne 2
114 .na
115 \fB\fB-S\fR\fIint\fR\fR
116 .ad
117 .RS 9n
118 Changes the size of the call stack from the default of \fB100\fRslots. Macros
119 take three slots, and non-macro arguments take one.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB-T\fR\fIint\fR\fR
126 .ad
127 .RS 9n
128 Changes the size of the token buffer from the default of \fB512\fRbytes.
129 .RE
131 .sp
132 .LP
133 To be effective, the above flags must appear before any file names and before
134 any \fB-D\fR or \fB-U\fR flags:
135 .sp
136 .ne 2
137 .na
138 \fB\fB-D\fR \fIname\fR[\fB=\fR\fBval\fR]\fR
139 .ad
140 .RS 17n
141 Defines \fIname\fR to \fBval\fR or to \fINULL\fR in \fBval\fR's absence.
142 .RE
144 .sp
145 .ne 2
146 .na
147 \fB\fB-U\fR\fIname\fR\fR
148 .ad
149 .RS 17n
150 Undefines \fIname\fR.
151 .RE
153 .SH OPERANDS
154 .sp
155 .LP
156 The following operand is supported:
157 .sp
158 .ne 2
159 .na
160 \fB\fIfile\fR\fR
161 .ad
162 .RS 8n
163 A path name of a text file to be processed. If no \fIfile\fR is given, or if it
164 is \(mi, the standard input is read.
165 .RE
167 .SH USAGE
168 .sp
169 .LP
170 The \fBm4\fR utility makes available the following built-in macros. These
171 macros can be redefined, but once this is done the original meaning is lost.
172 Their values are \fINULL\fR unless otherwise stated.
173 .sp
174 .ne 2
175 .na
176 \fB\fBchangequote\fR\fR
177 .ad
178 .RS 15n
179 Change quote symbols to the first and second arguments. The symbols can be up
180 to five characters long. \fBchangequote\fR without arguments restores the
181 original values (that is, \fB`\|'\fR).
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBchangecom\fR\fR
188 .ad
189 .RS 15n
190 Change left and right comment markers from the default \fB#\fR and
191 \fBNEWLINE\fR. With no arguments, the comment mechanism is effectively
192 disabled. With one argument, the left marker becomes the argument and the right
193 marker becomes \fBNEWLINE\fR. With two arguments, both markers are affected.
194 Comment markers can be up to five characters long.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fB\fBdecr\fR\fR
201 .ad
202 .RS 15n
203 Returns the value of its argument decremented by 1.
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fBdefine\fR\fR
210 .ad
211 .RS 15n
212 The second argument is installed as the value of the macro whose name is the
213 first argument. Each occurrence of \fB$\fR\fIn\fR in the replacement text,
214 where \fIn\fR is a digit, is replaced by the \fIn\fR-th argument. Argument 0 is
215 the name of the macro; missing arguments are replaced by the null string;
216 \fB$#\fR is replaced by the number of arguments; \fB$*\fR is replaced by a list
217 of all the arguments separated by commas; \fB$@\fR is like \fB$*\fR, but each
218 argument is quoted (with the current quotes).
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fBdefn\fR\fR
225 .ad
226 .RS 15n
227 Returns the quoted definition of its argument(s). It is useful for renaming
228 macros, especially built-ins.
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fB\fBdivert\fR\fR
235 .ad
236 .RS 15n
237 \fBm4\fR maintains 10 output streams, numbered 0-9. The final output is the
238 concatenation of the streams in numerical order. Initially stream 0 is the
239 current stream. The \fBdivert\fR macro changes the current output stream to its
240 (digit-string) argument. Output diverted to a stream other than 0 through 9 is
241 discarded.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fBdivnum\fR\fR
248 .ad
249 .RS 15n
250 Returns the value of the current output stream.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBdnl\fR\fR
257 .ad
258 .RS 15n
259 Reads and discards characters up to and including the next \fBNEWLINE\fR.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBdumpdef\fR\fR
266 .ad
267 .RS 15n
268 Prints current names and definitions, for the named items, or for all if no
269 arguments are given.
270 .RE
272 .sp
273 .ne 2
274 .na
275 \fB\fBerrprint\fR\fR
276 .ad
277 .RS 15n
278 Prints its argument on the diagnostic output file.
279 .RE
281 .sp
282 .ne 2
283 .na
284 \fB\fBifdef\fR\fR
285 .ad
286 .RS 15n
287 If the first argument is defined, the value is the second argument, otherwise
288 the third. If there is no third argument, the value is \fINULL\fR. The word
289 \fBunix\fR is predefined.
290 .RE
292 .sp
293 .ne 2
294 .na
295 \fB\fBifelse\fR\fR
296 .ad
297 .RS 15n
298 This macro has three or more arguments. If the first argument is the same
299 string as the second, then the value is the third argument. If not, and if
300 there are more than four arguments, the process is repeated with arguments 4,
301 5, 6 and 7. Otherwise, the value is either the fourth string, or, if it is not
302 present, \fINULL\fR.
303 .RE
305 .sp
306 .ne 2
307 .na
308 \fB\fBinclude\fR\fR
309 .ad
310 .RS 15n
311 Returns the contents of the file named in the argument.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fBincr\fR\fR
318 .ad
319 .RS 15n
320 Returns the value of its argument incremented by 1. The value of the argument
321 is calculated by interpreting an initial digit-string as a decimal number.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBindex\fR\fR
328 .ad
329 .RS 15n
330 Returns the position in its first argument where the second argument begins
331 (zero origin), or \(mi1 if the second argument does not occur.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fBlen\fR\fR
338 .ad
339 .RS 15n
340 Returns the number of characters in its argument.
341 .RE
343 .sp
344 .ne 2
345 .na
346 \fB\fBm4exit\fR\fR
347 .ad
348 .RS 15n
349 This macro causes immediate exit from \fBm4\fR. Argument 1, if given, is the
350 exit code; the default is \fB0\fR.
351 .RE
353 .sp
354 .ne 2
355 .na
356 \fB\fBm4wrap\fR\fR
357 .ad
358 .RS 15n
359 Argument 1 is pushed back at final \fBEOF\fR. Example:
360 \fBm4wrap(`cleanup(\|)')\fR
361 .RE
363 .sp
364 .ne 2
365 .na
366 \fB\fBmaketemp\fR\fR
367 .ad
368 .RS 15n
369 Fills in a string of "\fBX\fR" characters in its argument with the current
370 process \fBID\fR.
371 .RE
373 .sp
374 .ne 2
375 .na
376 \fB\fBpopdef\fR\fR
377 .ad
378 .RS 15n
379 Removes current definition of its argument(s), exposing the previous one, if
380 any.
381 .RE
383 .sp
384 .ne 2
385 .na
386 \fB\fBpushdef\fR\fR
387 .ad
388 .RS 15n
389 Like \fBdefine\fR, but saves any previous definition.
390 .RE
392 .sp
393 .ne 2
394 .na
395 \fB\fBshift\fR\fR
396 .ad
397 .RS 15n
398 Returns all but its first argument. The other arguments are quoted and pushed
399 back with commas in between. The quoting nullifies the effect of the extra scan
400 that is subsequently be performed.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fBsinclude\fR\fR
407 .ad
408 .RS 15n
409 This macro is identical to \fBinclude\fR, except that it says nothing if the
410 file is inaccessible.
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fBsubstr\fR\fR
417 .ad
418 .RS 15n
419 Returns a substring of its first argument. The second argument is a zero origin
420 number selecting the first character; the third argument indicates the length
421 of the substring. A missing third argument is taken to be large enough to
422 extend to the end of the first string.
423 .RE
425 .sp
426 .ne 2
427 .na
428 \fB\fBsyscmd\fR\fR
429 .ad
430 .RS 15n
431 This macro executes the command given in the first argument. No value is
432 returned.
433 .RE
435 .sp
436 .ne 2
437 .na
438 \fB\fBsysval\fR\fR
439 .ad
440 .RS 15n
441 This macro is the return code from the last call to \fBsyscmd\fR.
442 .RE
444 .sp
445 .ne 2
446 .na
447 \fB\fBtranslit\fR\fR
448 .ad
449 .RS 15n
450 Transliterates the characters in its first argument from the set given by the
451 second argument to the set given by the third. No abbreviations are permitted.
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBtraceon\fR\fR
458 .ad
459 .RS 15n
460 This macro with no arguments, turns on tracing for all macros (including
461 built-ins). Otherwise, turns on tracing for named macros.
462 .RE
464 .sp
465 .ne 2
466 .na
467 \fB\fBtraceoff\fR\fR
468 .ad
469 .RS 15n
470 Turns off trace globally and for any macros specified.
471 .RE
473 .sp
474 .ne 2
475 .na
476 \fB\fBundefine\fR\fR
477 .ad
478 .RS 15n
479 Removes the definition of the macro named in its argument.
480 .RE
482 .sp
483 .ne 2
484 .na
485 \fB\fBundivert\fR\fR
486 .ad
487 .RS 15n
488 This macro causes immediate output of text from diversions named as arguments,
489 or all diversions if no argument. Text can be undiverted into another
490 diversion. Undiverting discards the diverted text.
491 .RE
493 .SS "/usr/bin/m4"
494 .sp
495 .ne 2
496 .na
497 \fB\fBeval\fR\fR
498 .ad
499 .RS 8n
500 Evaluates its argument as an arithmetic expression, using 32-bit signed-integer
501 arithmetic. The following operators are supported: parentheses, unary -, unary
502 +, !, ~, *, /, %, +, -, relationals, bitwise &, |, &&, and ||. Octal and hex
503 numbers can be specified as in C. The second argument specifies the radix for
504 the result; the default is 10. The third argument can be used to specify the
505 minimum number of digits in the result.
506 .RE
508 .SS "/usr/xpg4/bin/m4"
509 .sp
510 .ne 2
511 .na
512 \fB\fBeval\fR\fR
513 .ad
514 .RS 8n
515 Evaluates its argument as an arithmetic expression, using 32-bit
516 signed-integer arithmetic. The following operators are supported: parentheses,
517 unary -, unary +, !, ~, *, /, %, +, -, <<, >>, relationals, bitwise &, |, &&,
518 and ||. Precedence and associativity are as in C. Octal and hex numbers can
519 also be specified as in C. The second argument specifies the radix for the
520 result; the default is 10. The third argument can be used to specify the
521 minimum number of digits in the result.
522 .RE
524 .SH EXAMPLES
525 .LP
526 \fBExample 1 \fRExamples of m4 files
527 .sp
528 .LP
529 If the file \fBm4src\fR contains the lines:
531 .sp
532 .in +2
533 .nf
534 The value of `VER' is "VER".
535 ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
536 ifelse(VER, 1, ``VER'' is `VER'.)
537 ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
538 end
539 .fi
540 .in -2
541 .sp
543 .sp
544 .LP
545 then the command:
547 .sp
548 .in +2
549 .nf
550 \fBm4 m4src\fR
551 .fi
552 .in -2
553 .sp
555 .sp
556 .LP
557 or the command:
559 .sp
560 .in +2
561 .nf
562 \fBm4 -U VER m4src\fR
563 .fi
564 .in -2
565 .sp
567 .sp
568 .LP
569 produces the output:
571 .sp
572 .in +2
573 .nf
574 The value of VER is "VER".
575 VER is not defined.
577 VER is not 2.
578 end
579 .fi
580 .in -2
581 .sp
583 .sp
584 .LP
585 The command:
587 .sp
588 .in +2
589 .nf
590 \fBm4 -D VER m4src\fR
591 .fi
592 .in -2
593 .sp
595 .sp
596 .LP
597 produces the output:
599 .sp
600 .in +2
601 .nf
602 The value of VER is "".
603 VER is defined to be .
605 VER is not 2.
606 end
607 .fi
608 .in -2
609 .sp
611 .sp
612 .LP
613 The command:
615 .sp
616 .in +2
617 .nf
618 \fBm4 -D VER=1 m4src\fR
619 .fi
620 .in -2
621 .sp
623 .sp
624 .LP
625 produces the output:
627 .sp
628 .in +2
629 .nf
630 The value of VER is "1".
631 VER is defined to be 1.
632 VER is 1.
633 VER is not 2.
634 end
635 .fi
636 .in -2
637 .sp
639 .sp
640 .LP
641 The command:
643 .sp
644 .in +2
645 .nf
646 \fBm4 -D VER=2 m4src\fR
647 .fi
648 .in -2
649 .sp
651 .sp
652 .LP
653 produces the output:
655 .sp
656 .in +2
657 .nf
658 The value of VER is "2".
659 VER is defined to be 2.
661 VER is 2.
662 end
663 .fi
664 .in -2
665 .sp
667 .SH ENVIRONMENT VARIABLES
668 .sp
669 .LP
670 See \fBenviron\fR(5) for descriptions of the following environment variables
671 that affect the execution of \fBm4\fR: \fBLANG\fR, \fBLC_ALL\fR,
672 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
673 .SH EXIT STATUS
674 .sp
675 .LP
676 The following exit values are returned:
677 .sp
678 .ne 2
679 .na
680 \fB\fB0\fR\fR
681 .ad
682 .RS 6n
683 Successful completion.
684 .RE
686 .sp
687 .ne 2
688 .na
689 \fB\fB>0\fR\fR
690 .ad
691 .RS 6n
692 An error occurred
693 .RE
695 .sp
696 .LP
697 If the \fBm4exit\fR macro is used, the exit value can be specified by the input
698 file.
700 .SH ATTRIBUTES
701 .sp
702 .LP
703 See \fBattributes\fR(5) for descriptions of the following attributes:
704 .SS "\fB/usr/xpg4/bin/m4\fR"
705 .sp
707 .sp
708 .TS
709 box;
710 c | c
711 l | l .
712 ATTRIBUTE TYPE ATTRIBUTE VALUE
713 _
714 Interface Stability Standard
715 .TE
717 .SH SEE ALSO
718 .sp
719 .LP
720 \fBas\fR(1), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)