diff options
Diffstat (limited to 'usr.bin/m4/m4.1')
| -rw-r--r-- | usr.bin/m4/m4.1 | 381 |
1 files changed, 0 insertions, 381 deletions
diff --git a/usr.bin/m4/m4.1 b/usr.bin/m4/m4.1 deleted file mode 100644 index ccd793d6e2a3b..0000000000000 --- a/usr.bin/m4/m4.1 +++ /dev/null @@ -1,381 +0,0 @@ -.\" @(#) $OpenBSD: m4.1,v 1.24 2002/04/18 18:57:23 espie Exp $ -.\" -.\" -.Dd January 26, 1993 -.Dt M4 1 -.Os -.Sh NAME -.Nm m4 -.Nd macro language processor -.Sh SYNOPSIS -.Nm m4 -.Op Fl d Ar flags -.Op Fl t Ar name -.Op Fl g -.Oo -.Fl D Ns Ar name Ns Op Ar =value -.Oc -.Op Fl U Ns Ar name -.Op Fl I Ar dirname -.Sh DESCRIPTION -The -.Nm m4 -utility is a macro processor that can be used as a front end to any -language (e.g., C, ratfor, fortran, lex, and yacc). -.Nm m4 -reads from the standard input and writes -the processed text to the standard output. -.Pp -Macro calls have the form name(argument1[, argument2, ..., argumentN]). -.Pp -There cannot be any space following the macro name and the open -parenthesis -.Pq Ql ( . -If the macro name is not followed by an open -parenthesis it is processed with no arguments. -.Pp -Macro names consist of a leading alphabetic or underscore -possibly followed by alphanumeric or underscore characters, e.g., -valid macro names match the pattern -.Dq [a-zA-Z_][a-zA-Z0-9_]* . -.Pp -In arguments to macros, leading unquoted space, tab, and newline -.Pq Ql \en -characters are ignored. -To quote strings, use left and right single -quotes (e.g., -.Sq \ this is a string with a leading space ) . -You can change the quote characters with the -.Ic changequote -built-in macro. -.Pp -Most built-ins don't make any sense without arguments, and hence are not -recognized as special when not followed by an open parenthesis. -.Pp -The options are as follows: -.Bl -tag -width Ds -.It Fl D Ns Ar name Ns Oo -.Ar =value -.Oc -Define the symbol -.Ar name -to have some value (or -.Dv NULL ) . -.It Fl "U" Ns Ar "name" -Undefine the symbol -.Ar name . -.It Fl I Ar "dirname" -Add directory -.Ar dirname -to the include path. -.It Fl d Ar "flags" -Set trace flags. -.Ar flags -may hold the following: -.Bl -tag -width Ds -.It Ar a -print macro arguments. -.It Ar c -print macro expansion over several lines. -.It Ar e -print result of macro expansion. -.It Ar f -print filename location. -.It Ar l -print line number. -.It Ar q -quote arguments and expansion with the current quotes. -.It Ar t -start with all macros traced. -.It Ar x -number macro expansions. -.It Ar V -turn on all options. -.El -.Pp -By default, trace is set to -.Qq eq . -.It Fl t Ar macro -Turn tracing on for -.Ar macro . -.It Fl g -Activate GNU-m4 compatibility mode. -In this mode, changequote with -two empty parameters deactivates quotes, translit handles simple character -ranges (e.g., a-z), regular expressions mimic emacs behavior, -and the number of diversions is unlimited. -.El -.Sh SYNTAX -.Nm m4 -provides the following built-in macros. -They may be redefined, losing their original meaning. -Return values are null unless otherwise stated. -.Bl -tag -width changequotexxx -.It Ic builtin -Calls a built-in by its name, overriding possible redefinitions. -.It Ic changecom -Change the start and end comment sequences. -The default is the pound sign -.Pq Ql # -and the newline character. -With no arguments comments are turned off. -The maximum length for a comment marker is five characters. -.It Ic changequote -Defines the quote symbols to be the first and second arguments. -The symbols may be up to five characters long. -If no arguments are -given it restores the default open and close single quotes. -.It Ic decr -Decrements the argument by 1. -The argument must be a valid numeric string. -.It Ic define -Define a new macro named by the first argument to have the -value of the second argument. -Each occurrence of -.Ql $n -(where -.Ar n -is 0 through 9) is replaced by the -.Ar n Ns 'th -argument. -.Ql $0 -is the name of the calling macro. -Undefined arguments are replaced by a null string. -.Ql $# -is replaced by the number of arguments; -.Ql $* -is replaced by all arguments comma separated; -.Ql $@ -is the same as -.Ql $* -but all arguments are quoted against further expansion. -.It Ic defn -Returns the quoted definition for each argument. -This can be used to rename -macro definitions (even for built-in macros). -.It Ic divert -There are 10 output queues (numbered 0-9). -At the end of processing -.Nm m4 -concatenates all the queues in numerical order to produce the -final output. -Initially the output queue is 0. -The divert -macro allows you to select a new output queue (an invalid argument -passed to divert causes output to be discarded). -.It Ic divnum -Returns the current output queue number. -.It Ic dnl -Discard input characters up to and including the next newline. -.It Ic dumpdef -Prints the names and definitions for the named items, or for everything -if no arguments are passed. -.It Ic errprint -Prints the first argument on the standard error output stream. -.It Ic esyscmd -Pass its first argument to a shell and returns the shell's standard output. -Note that the shell shares its standard input and standard error with -.Nm -.It Ic eval -Computes the first argument as an arithmetic expression using 32-bit -arithmetic. -Operators are the standard C ternary, arithmetic, logical, -shift, relational, bitwise, and parentheses operators. -You can specify -octal, decimal, and hexadecimal numbers as in C. -The second argument (if any) -specifies the radix for the result and the third argument (if any) -specifies the minimum number of digits in the result. -.It Ic expr -This is an alias for -.Ic eval . -.It Ic ifdef -If the macro named by the first argument is defined then return the second -argument, otherwise the third. -If there is no third argument, the value is -.Dv NULL . -The word -.Qq unix -is predefined. -.It Ic ifelse -If the first argument matches the second argument then -.Ic ifelse -returns -the third argument. -If the match fails the three arguments are -discarded and the next three arguments are used until there is -zero or one arguments left, either this last argument or -.Dv NULL -is returned if no other matches were found. -.It Ic include -Returns the contents of the file specified in the first argument. -If the file is not found as is, look through the include path: -first the directories specified with -.Fl I -on the command line, then the environment variable -.Ev M4PATH , -as a colon-separated list of directories. -Include aborts with an error message if the file cannot be included. -.It Ic incr -Increments the argument by 1. -The argument must be a valid numeric string. -.It Ic index -Returns the index of the second argument in the first argument (e.g., -.Ic index(the quick brown fox jumped, fox) -returns 16). -If the second -argument is not found index returns \-1. -.It Ic indir -Indirectly calls the macro whose name is passed as the first arguments, -with the remaining arguments passed as first, ... arguments. -.It Ic len -Returns the number of characters in the first argument. -Extra arguments -are ignored. -.It Ic m4exit -Immediately exits with the return value specified by the first argument, -0 if none. -.It Ic m4wrap -Allows you to define what happens at the final -.Dv EOF , -usually for cleanup purposes (e.g., -.Ic m4wrap("cleanup(tempfile)") -causes the macro cleanup to be -invoked after all other processing is done). -.It Ic maketemp -Translates the string -.Dq XXXXX -in the first argument with the current process -ID leaving other characters alone. -This can be used to create unique -temporary file names. -.It Ic paste -Includes the contents of the file specified by the first argument without -any macro processing. -Aborts with an error message if the file cannot be -included. -.It Ic patsubst -Substitutes a regular expression in a string with a replacement string. -Usual substitution patterns apply: an ampersand -.Pq Ql & -is replaced by the string matching the regular expression. -The string -.Ql \e# , -where -.Ql # -is a digit, is replaced by the corresponding back-reference. -.It Ic popdef -Restores the -.Ic pushdef Ns ed -definition for each argument. -.It Ic pushdef -Takes the same arguments as -.Ic define , -but it saves the definition on a -stack for later retrieval by -.Ic popdef . -.It Ic regexp -Finds a regular expression in a string. -If no further arguments are given, -it returns the first match position or \-1 if no match. -If a third argument -is provided, it returns the replacement string, with sub-patterns replaced. -.It Ic shift -Returns all but the first argument, the remaining arguments are -quoted and pushed back with commas in between. -The quoting -nullifies the effect of the extra scan that will subsequently be -performed. -.It Ic sinclude -Similar to -.Ic include , -except it ignores any errors. -.It Ic spaste -Similar to -.Ic paste , -except it ignores any errors. -.It Ic substr -Returns a substring of the first argument starting at the offset specified -by the second argument and the length specified by the third argument. -If no third argument is present it returns the rest of the string. -.It Ic syscmd -Passes the first argument to the shell. -Nothing is returned. -.It Ic sysval -Returns the return value from the last -.Ic syscmd . -.It Ic traceon -Enables tracing of macro expansions for the given arguments, or for all -macros if no argument is given. -.It Ic traceoff -Disables tracing of macro expansions for the given arguments, or for all -macros if no argument is given. -.It Ic translit -Transliterate the characters in the first argument from the set -given by the second argument to the set given by the third. -You cannot use -.Xr tr 1 -style abbreviations. -.It Ic undefine -Removes the definition for the macros specified by its arguments. -.It Ic undivert -Flushes the named output queues (or all queues if no arguments). -.It Ic unix -A pre-defined macro for testing the OS platform. -.It Ic __line__ -Returns the current file's line number. -.It Ic __file__ -Returns the current file's name. -.El -.Sh COMPATIBILITY -.Nm -follows the Single Unix 2 specification, along with a few extensions taken -from -.Nm gnu-m4 . -.Pp -The -.Fl s -option -.Po -.Xr cpp 1 's -#line directives -.Pc -is currently not supported. -Flags -.Fl I , -.Fl d , -.Fl t -are non-standard. -.Pp -The output format of tracing and of -.Ic dumpdef -are not specified in any standard, -are likely to change and should not be relied upon. -The current format of tracing is closely modelled on -.Nm gnu-m4 , -to allow -.Nm autoconf -to work. -.Pp -For portability, one should not use the macros -.Ic builtin , -.Ic esycmd , -.Ic expr , -.Ic indir , -.Ic paste , -.Ic patsubst , -.Ic regexp , -.Ic spaste , -.Ic unix , -.Ic __line__ , -.Ic __file__ . -.Pp -All builtins do expand without arguments in many other -.Nm m4 . -.Pp -Many other -.Nm -have dire size limitations with respect to buffer sizes. -.Sh AUTHORS -Ozan Yigit <oz@sis.yorku.ca> and Richard A. O'Keefe (ok@goanna.cs.rmit.OZ.AU). -GNU-m4 compatibility extensions by Marc Espie <espie@cvs.openbsd.org>. |