Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
M4(1)			  BSD General Commands Manual			 M4(1)

     m4	-- macro language processor

     m4	[-s] [-D name[=value]] [-U name] [file ...]

     The 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).  Each of the ar-
     gument files is processed in order.  If there are no files, or if a file-
     name is `-', the standard input is	read.  The processed text is sent to
     the standard output.

     Macro calls have the form name(argument1[,	argument2, ...,] argumentN).

     There cannot be any space following the macro name	and the	open parenthe-
     ses '('.  If the macro name is not	followed by an open parentheses	it is
     processed with no arguments.

     Macro names consist of a leading alphabetic or underscore possibly	fol-
     lowed by alphanumeric or underscore characters, therefore valid macro
     names match this pattern [a-zA-Z_][a-zA-Z0-9_]*.

     In	arguments to macros, leading unquoted space, tab and newline charac-
     ters are ignored.	To quote strings use left and right single quotes
     (e.g., ` this is a	string with a leading space').	You can	change the
     quote characters with the changequote built-in macro.

     The options are as	follows:

     -s			Emit #line directives for cpp(1).

     -D	name[=value]	Define the symbol name to have some value (or NULL).

     -U	name		Undefine the symbol name.

     m4	provides the following built-in	macros.	 They may be redefined,	losing
     their original meaning.  Return values are	NULL unless otherwise stated.

     changecom	     Change the	start and end comment sequences.  The default
		     is	the pound sign `#' and the newline character.  With no
		     arguments comments	are turned off.	 The maximum length
		     for a comment marker is five characters.

     changequote     Defines the quote symbols to be the first and second ar-
		     guments.  Note, only the first character of each argument
		     is	used.  If no arguments are given it restores the de-
		     fault open	and close single quotes.

     decr	     Decrements	the argument by	1.  The	argument must be a
		     valid numeric string.

     define	     Define a new macro	named by the first argument to have
		     the value of the second argument.	Each occurrence	of $n
		     (where n is 0 through 9) is replaced by the n'th argu-
		     ment.  $0 is the name of the calling macro.  Undefined
		     arguments are replaced by a NULL string.  $# is replaced
		     by	the number of arguments; $* is replaced	by all argu-
		     ments comma separated; $@ is the same as $* but all argu-
		     ments are quoted against further expansion.

     defn	     Returns the quoted	definition for each argument.  This
		     can be used to rename macro definitions (even for built-
		     in	macros).

     divert	     There are 10 output queues	(numbered 0-9).	 At the	end of
		     processing	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).

     divnum	     Returns the current output	queue number.

     dnl	     Discard input characters up to and	including the next

     dumpdef	     Prints the	names and definitions for the named items, or
		     for everything if no arguments are	passed.

     errprint	     Prints the	first argument on the standard error output

     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,	deci-
		     mal, and hexadecimal numbers as in	C.  The	second argu-
		     ment (if any) specifies the radix for the result and the
		     third argument (if	any) specifies the minimum number of
		     digits in the result.

     expr	     This is an	alias for eval.

     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 NULL.  The word
		     `unix' is predefined.

     ifelse	     If	the first argument matches the second argument then
		     ifelse returns the	third argument.	 If the	match fails
		     the three arguments are discarded and the next three ar-
		     guments are used until there is zero or one arguments
		     left, either this last argument or	NULL is	returned if no
		     other matches were	found.

     include	     Returns the contents of the file specified	in the first
		     argument.	Include	aborts with an error message if	the
		     file cannot be included.

     incr	     Increments	the argument by	1.  The	argument must be a
		     valid numeric string.

     index	     Returns the index of the second argument in the first ar-
		     gument (e.g., index(the quick brown fox jumped, fox) re-
		     turns 16).	 If the	second argument	is not found index re-
		     turns -1.

     len	     Returns the number	of characters in the first argument.
		     Extra arguments are ignored.

     m4exit	     Immediately exits with the	return value specified by the
		     first argument, 0 if none.

     m4wrap	     Allows you	to define what happens at the final EOF, usu-
		     ally for cleanup purposes (e.g., m4wrap("cleanup(temp-
		     file)") causes the	macro cleanup to be invoked after all
		     other processing is done.)

     maketemp	     Translates	the string XXXXX in the	first argument with
		     the current process ID leaving other characters alone.
		     This can be used to create	unique temporary file names.

     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.

     popdef	     Restores the pushdef'ed definition	for each argument.

     pushdef	     Takes the same arguments as define, but it	saves the def-
		     inition on	a stack	for later retrieval by popdef.

     shift	     Returns all but the first argument, the remaining argu-
		     ments are quoted and pushed back with commas in between.
		     The quoting nullifies the effect of the extra scan	that
		     will subsequently be performed.

     sinclude	     Similar to	include, except	it ignores any errors.

     spaste	     Similar to	paste, except it ignores any errors.

     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.

     syscmd	     Passes the	first argument to the shell.  Nothing is re-

     sysval	     Returns the return	value from the last syscmd.

     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	tr(1) style abbreviations.

     undefine	     Removes the definition for	the macro specified by the
		     first argument.

     undivert	     Flushes the named output queues (or all queues if no ar-

     unix	     A pre-defined macro for testing the OS platform.

     The m4 utility exits 0 on success,	and >0 if an error occurs.

     The exit status can be specified by the input file	using the m4exit


     The m4 utility is compatible with the IEEE	Std 1003.1-2001	("POSIX.1")
     specification with	the exception of the traceon and traceoff built-in
     macros, which are not implemented.

     The expr, paste, spaste and unix built-in macros are extensions to	the

     Ozan Yigit	<> and
     Richard A.	O'Keefe	<>

     The tracing macros	are not	implemented.

BSD			       January 26, 1993				   BSD


Want to link to this manual page? Use this URL:

home | help