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

FreeBSD Manual Pages

  
 
  

home | help
m4(1)				 User Commands				 m4(1)

NAME
       m4 - macro processor

SYNOPSIS
       /usr/ccs/bin/m4	[-e] [-s] [-B int] [-H int] [-S	int] [-T int] [	-Dname
       [=val]] ... [-U name] ... [file...]

       /usr/xpg4/bin/m4	[-e] [-s] [-B int] [-H int] [-S	int] [-T int] [	-Dname
       [ ...=val]] [-U name] ... [file...]

DESCRIPTION
       The  m4	utility	 is  a	macro processor	intended as a front end	for C,
       assembler, and other languages. Each of the argument files is processed
       in  order. If there are no files, or if a file is -, the	standard input
       is read.	The processed text is written on the standard output. Note: m4
       cannot  include more than nine nested files and will write a diagnostic
       message if that number is exceeded.

   Macro Syntax
       Macro calls have	the form:

       name(arg1,arg2, ..., argn)

       The open	parenthesis character, (, must immediately follow the name  of
       the macro. If the name of a defined macro is not	followed by a (, it is
       deemed to be a call of that macro with no  arguments.  Potential	 macro
       names  consist of alphanumeric characters and underscore	(_), where the
       first character is not a	digit.

       Leading unquoted	blanks,	 <TAB>s, and NEWLINEs are ignored  while  col-
       lecting	arguments.  Left  and  right  single  quotes are used to quote
       strings.	The value of a quoted string is	the  string  stripped  of  the
       quotes.

   Macro Processing
       When a macro name is recognized,	its arguments are collected by search-
       ing for a matching right	parenthesis. If	fewer arguments	 are  supplied
       than  are  in the macro definition, the trailing	arguments are taken to
       be NULL.	Macro evaluation proceeds normally during  the	collection  of
       the  arguments, and any commas or right parentheses that	happen to turn
       up within the value of a	nested call are	as effective as	those  in  the
       original	 input text. After argument collection,	the value of the macro
       is pushed back onto the input stream and	rescanned.

OPTIONS
       The options and their effects are as follows:

       -Bint	Changes	the size of the	push-back and argument collection buf-
		fers from the default of  4,096.

       -e	Operates  interactively. Interrupts are	ignored	and the	output
		is unbuffered.

       -Hint	Changes	the size of the	 symbol	 table	hash  array  from  the
		default	of  199. The size should be prime.

       -s	Enables	line sync output for the C preprocessor	(#line ...)

       -Sint	Changes	 the  size  of	the  call  stack  from	the default of
		100slots. Macros take three  slots,  and  non-macro  arguments
		take one.

       -Tint	Changes	 the  size  of	the  token  buffer from	the default of
		512bytes.

       To be effective,	the above flags	must appear before any file names  and
       before any -D or	-U flags:

       -D name[=val]   Defines name to val or to NULL in val's absence.

       -Uname	       Undefines name.

OPERANDS
       The following operand is	supported:

       file	A  path	 name  of  a  text file	to be processed. If no file is
		given, or if it	is -, the standard input is read.

USAGE
       The m4 utility makes available the  following  built-in	macros.	 These
       macros  may be redefined, but once this is done the original meaning is
       lost. Their values are  NULL unless otherwise stated.

       changequote     Change quote symbols to the first and second arguments.
		       The  symbols may	be up to five characters long. change-
		       quote without arguments restores	 the  original	values
		       (that is, `').

       changecom       Change  left and	right comment markers from the default
		       # and NEWLINE. With no arguments, the comment mechanism
		       is  effectively	disabled.  With	one argument, the left
		       marker  becomes	the  argument  and  the	 right	marker
		       becomes	NEWLINE.  With two arguments, both markers are
		       affected. Comment markers may be	up to five  characters
		       long.

       decr	       Returns the value of its	argument decremented by	1.

       define	       The  second  argument  is installed as the value	of the
		       macro whose name	is the first argument. Each occurrence
		       of  $n  in the replacement text,	where n	is a digit, is
		       replaced	by the n-th argument. Argument 0 is  the  name
		       of  the	macro;	missing	 arguments are replaced	by the
		       null string; $# is replaced by the number of arguments;
		       $* is replaced by a list	of all the arguments separated
		       by commas; $@ is	like $*, but each argument  is	quoted
		       (with the current quotes).

       defn	       Returns the quoted definition of	its argument(s). It is
		       useful for renaming macros, especially built-ins.

       divert	       m4 maintains 10 output streams, numbered	0-9. The final
		       output is the concatenation of the streams in numerical
		       order. Initially	stream 0 is the	 current  stream.  The
		       divert  macro  changes the current output stream	to its
		       (digit-string) argument.	Output diverted	 to  a	stream
		       other than 0 through 9 is discarded.

       divnum	       Returns the value of the	current	output stream.

       dnl	       Reads  and  discards characters up to and including the
		       next NEWLINE.

       dumpdef	       Prints current names and	 definitions,  for  the	 named
		       items, or for all if no arguments are given.

       errprint	       Prints its argument on the diagnostic output file.

   /usr/ccs/bin/m4
       eval	       Evaluates  its  argument	 as  an	arithmetic expression,
		       using 32-bit signed-integer arithmetic.	The  following
		       operators are supported:	parentheses, unary -, unary +,
		       !, ~, *,	/, %, +, -, relationals, bitwise &, |, &&, and
		       ||.    Octal  and hex numbers may be specified as in C.
		       The second argument specifies the radix for the result;
		       the  default  is	 10. The third argument	may be used to
		       specify the minimum number of digits in the result.

   /usr/xpg4/bin/m4
       eval	       Evaluates its argument  as  an  arithmetic  expression,
		       using  32-bit  signed-integer arithmetic. The following
		       operators are supported:	parentheses, unary -, unary +,
		       !, ~, *,	/, %, +, -, <<,	>>, relationals, bitwise &, |,
		       &&, and ||.  Precedence and associativity are as	in  C.
		       Octal  and  hex	numbers	may also be specified as in C.
		       The second argument specifies the radix for the result;
		       the  default  is	 10. The third argument	may be used to
		       specify the minimum number of digits in the result.

       ifdef	       If the first argument is	defined, the value is the sec-
		       ond  argument,  otherwise  the  third.	If there is no
		       third argument, the value is  NULL. The	word  unix  is
		       predefined.

       ifelse	       This  macro  has	 three or more arguments. If the first
		       argument	is the same string as  the  second,  then  the
		       value  is  the third argument. If not, and if there are
		       more than four arguments, the process is	repeated  with
		       arguments 4, 5, 6 and 7.	Otherwise, the value is	either
		       the fourth string, or, if it is not present, NULL.

       include	       Returns the contents of the file	named in the argument.

       incr	       Returns the value of its	argument incremented by	1. The
		       value  of the argument is calculated by interpreting an
		       initial digit-string as a decimal number.

       index	       Returns the position in its first  argument  where  the
		       second argument begins (zero origin), or	-1 if the sec-
		       ond argument does not occur.

       len	       Returns the number of characters	in its argument.

       m4exit	       This macro causes immediate exit	from m4.  Argument  1,
		       if given, is the	exit code; the default is  0.

       m4wrap	       Argument	 1  will be pushed back	at final EOF. Example:
		       m4wrap(`cleanup()')

       maketemp	       Fills in	a string of "X"	 characters  in	 its  argument
		       with the	current	process	ID.

       popdef	       Removes current definition of its argument(s), exposing
		       the previous one, if any.

       pushdef	       Like define, but	saves any previous definition.

       shift	       Returns all but its first argument. The other arguments
		       are  quoted and pushed back with	commas in between. The
		       quoting nullifies the effect of	the  extra  scan  that
		       will subsequently be performed.

       sinclude	       This macro is identical to include, except that it says
		       nothing if the file is inaccessible.

       substr	       Returns a substring of its first	argument.  The	second
		       argument	 is  a	zero origin number selecting the first
		       character; the third argument indicates the  length  of
		       the  substring. A missing third argument	is taken to be
		       large enough to extend to the end of the	first string.

       syscmd	       This macro executes the	command	 given	in  the	 first
		       argument. No value is returned.

       sysval	       This  macro  is	the  return code from the last call to
		       syscmd.

       translit	       Transliterates the characters  in  its  first  argument
		       from  the  set  given by	the second argument to the set
		       given by	the third. No abbreviations are	permitted.

       traceon	       This macro with no arguments, turns on tracing for  all
		       macros (including built-ins). Otherwise,	turns on trac-
		       ing for named macros.

       traceoff	       Turns off trace globally	and for	any macros specified.

       undefine	       Removes the definition of the macro named in its	 argu-
		       ment.

       undivert	       This  macro causes immediate output of text from	diver-
		       sions named as arguments, or all	diversions if no argu-
		       ment.  Text  may	 be undiverted into another diversion.
		       Undiverting discards the	diverted text.

EXAMPLES
       Example 1: Examples of m4 files

       If the file m4src contains the lines:

	       The value of `VER' is "VER".
	       ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
	       ifelse(VER, 1, ``VER'' is `VER'.)
	       ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not	2.)
	       end

       then the	command:

	       m4 m4src

       or the command:

	       m4 -U VER m4src

       produces	the output:

	       The value of VER	is "VER".
	       VER is not defined.

	       VER is not 2.
	       end

       The command:

	       m4 -D VER m4src

       produces	the output:

	       The value of VER	is "".
	       VER is defined to be .

	       VER is not 2.
	       end

       The command:

	       m4 -D VER=1 m4src

       produces	the output:

	       The value of VER	is "1".
	       VER is defined to be 1.
	       VER is 1.
	       VER is not 2.
	       end

       The command:

	       m4 -D VER=2 m4src

       produces	the output:

	       The value of VER	is "2".
	       VER is defined to be 2.

	       VER is 2.
	       end

ENVIRONMENT VARIABLES
       See environ(5) for descriptions of the following	environment  variables
       that  affect  the execution of m4: LANG,	LC_ALL,	LC_CTYPE, LC_MESSAGES,
       and NLSPATH.

EXIT STATUS
       The following exit values are returned:

       0	Successful completion.

       >0	An error occurred

       If the m4exit macro is used, the	exit value can	be  specified  by  the
       input file.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

   /usr/ccs/bin/m4
       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

   /usr/xpg4/bin/m4
       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWxcu4			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       as(1), attributes(5), environ(5), standards(5)

SunOS 5.10			  19 Aug 2002				 m4(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=m4&sektion=1&manpath=SunOS+5.10>

home | help