![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to m4.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / adm / man1|
Return to m4.1 CVS log | Up to [Research Unix] / researchv10dc / man / adm / man1 |
1.1 root 1: .TH M4 1
2: .CT 1 prog_c
3: .SH NAME
4: m4 \(mi macro processor
5: .SH SYNOPSIS
6: .B m4
7: [
8: .I option ...
9: ]
10: [
11: .I file ...
12: ]
13: .SH DESCRIPTION
14: .I M4\^
15: is a macro processor
16: intended as a front end for C and other languages.
17: Each of the argument files is processed in order;
18: if there are no files, or if a file name is
19: .BR - ,
20: the standard input is read.
21: The processed text is written on the standard output.
22: .PP
23: The options and their effects are as follows:
24: .TP
25: .B -e
26: Operate interactively.
27: Interrupts are ignored and the output is unbuffered.
28: Using this mode requires a special state of mind.
29: .TP
30: .B -s
31: Enable line sync output for the C preprocessor,
32: .RB ( #line " .\|.\|.\|)"
33: .TP
34: .BI -B int\^
35: Change the size of the push-back and argument collection
36: buffers from the default of 4,096.
37: .TP
38: .BI -H int\^
39: Change the size of the symbol table hash array from the
40: default of 199.
41: The size should be prime.
42: .TP
43: .BI -S int\^
44: Change the size of the call stack from the default of 100 slots.
45: Macros take three slots, and non-macro arguments take one.
46: .TP
47: .BI -T int\^
48: Change the size of the token buffer from the default of 512 bytes.
49: .PP
50: The preceding options must appear before any
51: file names or
52: .B -D
53: or
54: .B -U
55: options.
56: .TP
57: \f5-D\fP\f2name\^\fP[\f5=\fP\f2val\^\fP]
58: Defines
59: .I name\^
60: to
61: .I val\^
62: or to null if
63: .I val
64: is missing.
65: .TP
66: .BI -U name\^
67: undefines
68: .IR name .
69: .PP
70: Macro calls
71: have the form:
72: .IP
73: .L name(arg1,arg2, .\|.\|., argn)
74: .PP
75: The
76: .B (
77: must immediately follow the name of the macro.
78: If a defined macro name is not followed by a
79: .BR ( ,
80: it is deemed to have no arguments.
81: Leading unquoted blanks, tabs, and new-lines are ignored while collecting arguments.
82: Potential macro names consist of alphabetic letters,
83: digits, and underscore
84: .BR _ ,
85: where the first character is not a digit.
86: .PP
87: Left and right single quotes are used to quote strings.
88: The value of a quoted string is the string stripped of the quotes.
89: .PP
90: When a macro name is recognized,
91: its arguments are collected by searching for a matching right
92: parenthesis.
93: Macro evaluation proceeds normally during the collection of the arguments,
94: and any commas or right parentheses
95: which happen to turn up within the value of a nested
96: call are as effective as those in the original input text.
97: After argument collection,
98: the value of the macro is pushed back onto the input stream
99: and rescanned.
100: .PP
101: The value of a macro is obtained by replacing
102: each occurrence of
103: .BI $ n\^
104: in the replacement text,
105: where
106: .I n\^
107: is a digit,
108: with the
109: .IR n -th
110: argument.
111: Argument 0 is the name of the macro;
112: missing arguments are replaced by the null string;
113: .B $#
114: is replaced by the number of arguments;
115: .B $*
116: is replaced by a list of all the arguments separated by commas;
117: .B $@
118: is like
119: .BR $* ,
120: but each argument is quoted (with the current quotes).
121: .PP
122: .I M4\^
123: makes available the following built-in macros.
124: They may be redefined, but once this is done the original meaning is lost.
125: Their values are null unless otherwise stated.
126: .TP 12
127: .B define
128: the second argument is installed as the replacement text of the macro
129: whose name is the first argument.
130: .TP
131: .B undefine
132: Remove the definition of the macro named in the argument.
133: .TP
134: .B defn
135: Return the quoted definition of the argument(s);
136: useful for renaming macros, especially built-ins.
137: .TP
138: .B pushdef
139: Like
140: .IR define ,
141: but save any previous definition.
142: .TP
143: .B popdef
144: Remove current definition of the argument(s),
145: exposing the previous one if any.
146: .TP
147: .B ifdef
148: If the first argument is defined, the value is the second argument, otherwise the third.
149: If there is no third argument, the value is null.
150: The word
151: .L unix\^
152: is predefined on
153: .SM UNIX
154: versions of
155: .IR m4 .
156: .TP
157: .B shift
158: Return all but the first argument.
159: The other arguments pushed back with
160: commas in between and quoted to
161: nullify the effect of the extra scan.
162: .TP
163: .B changequote
164: Change quote symbols to the first and second arguments.
165: The symbols may be up to five characters long.
166: .B Changequote\^
167: without arguments restores the original values
168: (i.e.,
169: .LR `\|' ).
170: .TP
171: .B changecom
172: Change left and right comment markers from the default
173: .B #
174: and new-line.
175: With no arguments, the comment mechanism is effectively
176: disabled.
177: With one argument, the left marker becomes the argument and
178: the right marker becomes new-line.
179: With two arguments, both markers are affected.
180: Comment markers may be up to five characters long.
181: .TP
182: .B divert
183: .I m4\^
184: Switch output to one of 10 streams,
185: numbered 0-9 designated by the argument.
186: The final output is the concatenation of the streams
187: in numerical order;
188: stream 0 is the current initially.
189: Output to a stream other than 0 through 9
190: is discarded.
191: .TP
192: .B undivert
193: Cause immediate output of text from diversions named as
194: arguments, or all diversions if no argument.
195: Text may be undiverted into another diversion.
196: Once undiverted, the diverted text is no longer contained in that diversion.
197: .TP
198: .B divnum
199: Return the name of the current output stream.
200: .TP
201: .B dnl
202: reads and discards characters up to and including the next new-line.
203: .TP
204: .B ifelse
205: If the first argument is the same string as the second,
206: then the value is the third argument.
207: If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6 and 7.
208: Otherwise, the value is either the fourth string, or, if that is not present,
209: null.
210: .TP
211: .B incr
212: Return the value of the argument incremented by 1.
213: The value of the argument is calculated
214: by interpreting an initial digit-string as a decimal number.
215: .TP
216: .B decr
217: Return the value of the argument decremented by 1.
218: .TP
219: .B eval
220: Evaluate the argument as an arithmetic expression, using 32-bit arithmetic.
221: C-like operators include
222: .BR +-*/% ,
223: bitwise
224: .BR &|^~ ;
225: relationals; parentheses.
226: Octal and hex numbers may be specified as in C.
227: The second argument specifies the radix for the result;
228: the default is 10.
229: The third argument may be used to specify the minimum number
230: of digits in the result.
231: .TP
232: .B len
233: Returns the number of characters in the argument.
234: .TP
235: .B index
236: Return the position in the first argument where the second argument begins (zero origin),
237: or \-1 if the second argument does not occur.
238: .TP
239: .B substr
240: Return a substring of the first argument.
241: The second argument is a zero origin
242: number selecting the first character;
243: the third argument indicates the length of the substring.
244: A missing third argument is taken to be large enough to extend to
245: the end of the first string.
246: .TP
247: .B translit
248: Transliterate the characters in the first argument
249: from the set given by the second argument to the set given by the third,
250: deleting characters that lack a correspondent in the third set.
251: There is no character-range notation.
252: .TP
253: .B include
254: Return the contents of the file named in the argument.
255: .TP
256: .B sinclude
257: Same, but give no diagnostic if the file is inaccessible.
258: .TP
259: .B syscmd
260: Execute the
261: .SM UNIX
262: command given in the first argument.
263: No value is returned.
264: .TP
265: .B sysval
266: The return code from the last call to
267: .IR syscmd .
268: .TP
269: .B maketemp
270: Rill in a string of
271: .LR X
272: characters in the argument with the current process id.
273: .TP
274: .B m4exit
275: Exit immediately from
276: .IR m4 .
277: Argument 1, if given, is the exit code;
278: the default is 0.
279: .TP
280: .B m4wrap
281: Push the argument back at the end of the input.
282: Example:
283: .L m4wrap(`cleanup()')
284: .TP
285: .B errprint
286: Prints the argument
287: on the standard error file.
288: .TP
289: .B dumpdef
290: Print current names and definitions,
291: for the named items, or for all if no arguments are given.
292: .TP
293: .B traceon
294: If there are no arguments, turn on tracing for all macros
295: (including built-ins).
296: Otherwise, turn on tracing for named macros.
297: .TP
298: .B traceoff
299: Turn off trace globally and for any macros specified.
300: Macros specifically traced by
301: .B traceon\^
302: can be untraced only by specific calls to
303: .BR traceoff .
304: .SH EXAMPLES
305: .EX
306: define(fib,`ifelse(define(`n',eval($1))n,0,1,n,1,1,dnl()
307: `eval(fib(n-1)+fib($1-2))')')dnl()
308: fib(2*3)
309: .EE
310: .ns
311: .IP
312: Recursively evaluate a Fibonacci number.
313: The inner
314: .B define
315: avoids some reevaluations.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.