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