diff options
Diffstat (limited to 'static/unix-v10/man1/m4.1')
| -rw-r--r-- | static/unix-v10/man1/m4.1 | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/static/unix-v10/man1/m4.1 b/static/unix-v10/man1/m4.1 new file mode 100644 index 00000000..1e2fd5c5 --- /dev/null +++ b/static/unix-v10/man1/m4.1 @@ -0,0 +1,315 @@ +.TH M4 1 +.CT 1 prog_c +.SH NAME +m4 \(mi macro processor +.SH SYNOPSIS +.B m4 +[ +.I option ... +] +[ +.I file ... +] +.SH DESCRIPTION +.I M4\^ +is a macro processor +intended as a front end for C and other languages. +Each of the argument files is processed in order; +if there are no files, or if a file name is +.BR - , +the standard input is read. +The processed text is written on the standard output. +.PP +The options and their effects are as follows: +.TP +.B -e +Operate interactively. +Interrupts are ignored and the output is unbuffered. +Using this mode requires a special state of mind. +.TP +.B -s +Enable line sync output for the C preprocessor, +.RB ( #line " .\|.\|.\|)" +.TP +.BI -B int\^ +Change the size of the push-back and argument collection +buffers from the default of 4,096. +.TP +.BI -H int\^ +Change the size of the symbol table hash array from the +default of 199. +The size should be prime. +.TP +.BI -S int\^ +Change the size of the call stack from the default of 100 slots. +Macros take three slots, and non-macro arguments take one. +.TP +.BI -T int\^ +Change the size of the token buffer from the default of 512 bytes. +.PP +The preceding options must appear before any +file names or +.B -D +or +.B -U +options. +.TP +\f5-D\fP\f2name\^\fP[\f5=\fP\f2val\^\fP] +Defines +.I name\^ +to +.I val\^ +or to null if +.I val +is missing. +.TP +.BI -U name\^ +undefines +.IR name . +.PP +Macro calls +have the form: +.IP +.L name(arg1,arg2, .\|.\|., argn) +.PP +The +.B ( +must immediately follow the name of the macro. +If a defined macro name is not followed by a +.BR ( , +it is deemed to have no arguments. +Leading unquoted blanks, tabs, and new-lines are ignored while collecting arguments. +Potential macro names consist of alphabetic letters, +digits, and underscore +.BR _ , +where the first character is not a digit. +.PP +Left and right single quotes are used to quote strings. +The value of a quoted string is the string stripped of the quotes. +.PP +When a macro name is recognized, +its arguments are collected by searching for a matching right +parenthesis. +Macro evaluation proceeds normally during the collection of the arguments, +and any commas or right parentheses +which happen to turn up within the value of a nested +call are as effective as those in the original input text. +After argument collection, +the value of the macro is pushed back onto the input stream +and rescanned. +.PP +The value of a macro is obtained by replacing +each occurrence of +.BI $ n\^ +in the replacement text, +where +.I n\^ +is a digit, +with the +.IR n -th +argument. +Argument 0 is the name of the macro; +missing arguments are replaced by the null string; +.B $# +is replaced by the number of arguments; +.B $* +is replaced by a list of all the arguments separated by commas; +.B $@ +is like +.BR $* , +but each argument is quoted (with the current quotes). +.PP +.I M4\^ +makes available the following built-in macros. +They may be redefined, but once this is done the original meaning is lost. +Their values are null unless otherwise stated. +.TP 12 +.B define +the second argument is installed as the replacement text of the macro +whose name is the first argument. +.TP +.B undefine +Remove the definition of the macro named in the argument. +.TP +.B defn +Return the quoted definition of the argument(s); +useful for renaming macros, especially built-ins. +.TP +.B pushdef +Like +.IR define , +but save any previous definition. +.TP +.B popdef +Remove current definition of the argument(s), +exposing the previous one if any. +.TP +.B ifdef +If the first argument is defined, the value is the second argument, otherwise the third. +If there is no third argument, the value is null. +The word +.L unix\^ +is predefined on +.SM UNIX +versions of +.IR m4 . +.TP +.B shift +Return all but the first argument. +The other arguments pushed back with +commas in between and quoted to +nullify the effect of the extra scan. +.TP +.B changequote +Change quote symbols to the first and second arguments. +The symbols may be up to five characters long. +.B Changequote\^ +without arguments restores the original values +(i.e., +.LR `\|' ). +.TP +.B changecom +Change left and right comment markers from the default +.B # +and new-line. +With no arguments, the comment mechanism is effectively +disabled. +With one argument, the left marker becomes the argument and +the right marker becomes new-line. +With two arguments, both markers are affected. +Comment markers may be up to five characters long. +.TP +.B divert +.I m4\^ +Switch output to one of 10 streams, +numbered 0-9 designated by the argument. +The final output is the concatenation of the streams +in numerical order; +stream 0 is the current initially. +Output to a stream other than 0 through 9 +is discarded. +.TP +.B undivert +Cause immediate output of text from diversions named as +arguments, or all diversions if no argument. +Text may be undiverted into another diversion. +Once undiverted, the diverted text is no longer contained in that diversion. +.TP +.B divnum +Return the name of the current output stream. +.TP +.B dnl +reads and discards characters up to and including the next new-line. +.TP +.B ifelse +If the first argument is the same string as the second, +then the value is the third argument. +If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6 and 7. +Otherwise, the value is either the fourth string, or, if that is not present, +null. +.TP +.B incr +Return the value of the argument incremented by 1. +The value of the argument is calculated +by interpreting an initial digit-string as a decimal number. +.TP +.B decr +Return the value of the argument decremented by 1. +.TP +.B eval +Evaluate the argument as an arithmetic expression, using 32-bit arithmetic. +C-like operators include +.BR +-*/% , +bitwise +.BR &|^~ ; +relationals; parentheses. +Octal and hex numbers may be specified as in C. +The second argument specifies the radix for the result; +the default is 10. +The third argument may be used to specify the minimum number +of digits in the result. +.TP +.B len +Returns the number of characters in the argument. +.TP +.B index +Return the position in the first argument where the second argument begins (zero origin), +or \-1 if the second argument does not occur. +.TP +.B substr +Return a substring of the first argument. +The second argument is a zero origin +number selecting the first character; +the third argument indicates the length of the substring. +A missing third argument is taken to be large enough to extend to +the end of the first string. +.TP +.B translit +Transliterate the characters in the first argument +from the set given by the second argument to the set given by the third, +deleting characters that lack a correspondent in the third set. +There is no character-range notation. +.TP +.B include +Return the contents of the file named in the argument. +.TP +.B sinclude +Same, but give no diagnostic if the file is inaccessible. +.TP +.B syscmd +Execute the +.SM UNIX +command given in the first argument. +No value is returned. +.TP +.B sysval +The return code from the last call to +.IR syscmd . +.TP +.B maketemp +Fill in a string of +.LR X +characters in the argument with the current process id. +.TP +.B m4exit +Exit immediately from +.IR m4 . +Argument 1, if given, is the exit code; +the default is 0. +.TP +.B m4wrap +Push the argument back at the end of the input. +Example: +.L m4wrap(`cleanup()') +.TP +.B errprint +Prints the argument +on the standard error file. +.TP +.B dumpdef +Print current names and definitions, +for the named items, or for all if no arguments are given. +.TP +.B traceon +If there are no arguments, turn on tracing for all macros +(including built-ins). +Otherwise, turn on tracing for named macros. +.TP +.B traceoff +Turn off trace globally and for any macros specified. +Macros specifically traced by +.B traceon\^ +can be untraced only by specific calls to +.BR traceoff . +.SH EXAMPLES +.EX +define(fib,`ifelse(define(`n',eval($1))n,0,1,n,1,1,dnl() +`eval(fib(n-1)+fib($1-2))')')dnl() +fib(2*3) +.EE +.ns +.IP +Recursively evaluate a Fibonacci number. +The inner +.B define +avoids some reevaluations. |