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