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