Annotation of src/usr.bin/m4/m4.1, Revision 1.3
1.3 ! deraadt 1: .\" @(#) $OpenBSD: m4.1,v 1.2 1995/12/14 02:57:00 deraadt Exp $
1.1 deraadt 2: .\"
3: .\"
4: .Dd January 26, 1993
5: .Dt m4 1
6: .Os
7: .Sh NAME
8: .Nm m4
9: .Nd macro language processor
10: .Sh SYNOPSIS
11: .Nm m4
12: .Oo
13: .Fl D Ns Ar name Ns Op Ar =value
14: .Oc
15: .Op Fl U Ns Ar name
16: .Sh DESCRIPTION
17: The
18: .Nm m4
19: utility is a macro processor that can be used as a front end to any
20: language (e.g., C, ratfor, fortran, lex, and yacc).
21: .Nm m4
22: reads from the standard input and writes
23: the processed text to the standard output.
24: .Pp
25: Macro calls have the form name(argument1[, argument2, ...,] argumentN).
26: .Pp
27: There cannot be any space following the macro name and the open
28: parentheses '('. If the macro name is not followed by an open
29: parentheses it is processed with no arguments.
30: .Pp
31: Macro names consist of a leading alphabetic or underscore
32: possibly followed by alphanumeric or underscore characters, therefore
33: valid macro names match this pattern [a-zA-Z_][a-zA-Z0-9_]*.
34: .Pp
35: In arguments to macros, leading unquoted space, tab and newline
36: characters are ignored. To quote strings use left and right single
37: quotes (e.g., ` this is a string with a leading space'). You can change
38: the quote characters with the changequote built-in macro.
39: .Pp
40: The options are as follows:
41: .Bl -tag -width "-Dname[=value]xxx"
42: .It Fl D Ns Ar name Ns Oo
43: .Ar =value
44: .Oc
45: Define the symbol
46: .Ar name
47: to have some value (or NULL).
48: .It Fl "U" Ns Ar "name"
49: Undefine the symbol
50: .Ar name .
51: .El
52: .Sh SYNTAX
53: .Nm m4
54: provides the following built-in macros. They may be
1.2 deraadt 55: redefined, losing their original meaning.
1.1 deraadt 56: Return values are NULL unless otherwise stated.
57: .Bl -tag -width changequotexxx
58: .It changecom
59: Change the start and end comment sequences. The default is
60: the pound sign `#' and the newline character. With no arguments
61: comments are turned off. The maximum length for a comment marker is
62: five characters.
63: .It changequote
64: Defines the quote symbols to be the first and second arguments.
65: The symbols may be up to five characters long. If no arguments are
66: given it restores the default open and close single quotes.
67: .It decr
68: Decrements the argument by 1. The argument must be a valid numeric string.
69: .It define
70: Define a new macro named by the first argument to have the
71: value of the second argument. Each occurrence of $n (where n
72: is 0 through 9) is replaced by the n'th argument. $0 is the name
73: of the calling macro. Undefined arguments are replaced by a
74: NULL string. $# is replaced by the number of arguments; $*
75: is replaced by all arguments comma separated; $@ is the same
76: as $* but all arguments are quoted against further expansion.
77: .It defn
78: Returns the quoted definition for each argument. This can be used to rename
79: macro definitions (even for built-in macros).
80: .It divert
81: There are 10 output queues (numbered 0-9).
82: At the end of processing
83: .Nm m4
84: concatenates all the queues in numerical order to produce the
85: final output. Initially the output queue is 0. The divert
86: macro allows you to select a new output queue (an invalid argument
87: passed to divert causes output to be discarded).
88: .It divnum
89: Returns the current output queue number.
90: .It dnl
91: Discard input characters up to and including the next newline.
92: .It dumpdef
93: Prints the names and definitions for the named items, or for everything
94: if no arguments are passed.
95: .It errprint
96: Prints the first argument on the standard error output stream.
97: .It eval
98: Computes the first argument as an arithmetic expression using 32-bit
99: arithmetic. Operators are the standard C ternary, arithmetic, logical,
100: shift, relational, bitwise, and parentheses operators. You can specify
101: octal, decimal, and hexadecimal numbers as in C. The second argument (if
102: any) specifies the radix for the result and the third argument (if
103: any) specifies the minimum number of digits in the result.
104: .It expr
105: This is an alias for eval.
106: .It ifdef
107: If the macro named by the first argument is defined then return the second
108: argument, otherwise the third. If there is no third argument,
109: the value is NULL. The word `unix' is predefined.
110: .It ifelse
111: If the first argument matches the second argument then ifelse returns
112: the third argument. If the match fails the three arguments are
113: discarded and the next three arguments are used until there is
114: zero or one arguments left, either this last argument or NULL is
115: returned if no other matches were found.
116: .It include
117: Returns the contents of the file specified in the first argument.
118: Include aborts with an error message if the file cannot be included.
119: .It incr
120: Increments the argument by 1. The argument must be a valid numeric string.
121: .It index
122: Returns the index of the second argument in the first argument (e.g.,
123: index(the quick brown fox jumped, fox) returns 16). If the second
124: argument is not found index returns -1.
125: .It len
126: Returns the number of characters in the first argument. Extra arguments
127: are ignored.
128: .It m4exit
129: Immediately exits with the return value specified by the first argument,
130: 0 if none.
131: .It m4wrap
132: Allows you to define what happens at the final EOF, usually for cleanup
133: purposes (e.g., m4wrap("cleanup(tempfile)") causes the macro cleanup to
134: invoked after all other processing is done.)
135: .It maketemp
136: Translates the string XXXXX in the first argument with the current process
137: ID leaving other characters alone. This can be used to create unique
138: temporary file names.
139: .It paste
140: Includes the contents of the file specified by the first argument without
141: any macro processing. Aborts with an error message if the file cannot be
142: included.
143: .It popdef
144: Restores the pushdef'ed definition for each argument.
145: .It pushdef
146: Takes the same arguments as define, but it saves the definition on a
147: stack for later retrieval by popdef.
148: .It shift
149: Returns all but the first argument, the remaining arguments are
150: quoted and pushed back with commas in between. The quoting
151: nullifies the effect of the extra scan that will subsequently be
152: performed.
153: .It sinclude
154: Similar to include, except it ignores any errors.
155: .It spaste
156: Similar to spaste, except it ignores any errors.
157: .It substr
158: Returns a substring of the first argument starting at the offset specified
159: by the second argument and the length specified by the third argument.
160: If no third argument is present it returns the rest of the string.
161: .It syscmd
162: Passes the first argument to the shell. Nothing is returned.
163: .It sysval
164: Returns the return value from the last syscmd.
165: .It translit
166: Transliterate the characters in the first argument from the set
167: given by the second argument to the set given by the third. You cannot
168: use
169: .Xr tr 1
170: style abbreviations.
171: .It undefine
172: Removes the definition for the macro specified by the first argument.
173: .It undivert
174: Flushes the named output queues (or all queues if no arguments).
175: .It unix
176: A pre-defined macro for testing the OS platform.
177: .El
178: .Sh AUTHOR
179: Ozan Yigit <oz@sis.yorku.ca> and Richard A. O'Keefe (ok@goanna.cs.rmit.OZ.AU)
![[BACK]](/icons/back.gif){kind=icon}
Return to m4.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / m4