unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 m4(1)								       m4(1)




 NAME
      m4 - macro processor

 SYNOPSIS
      m4 [options] [file ...]

 DESCRIPTION
      m4 is a macro processor intended as a front end for Ratfor, C, and
      other languages.	Each of the argument files is processed in order; if
      there are no files, or if a file name is -, standard input is read.
      The processed text is written to standard output.

    Options
      m4 recognizes the following options:

	   -e	     Operate interactively.  Interrupts are ignored and the
		     output is unbuffered.  Using this mode may be very
		     difficult.

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

	   -Bint     Change the size of the push-back and argument
		     collection buffers from the default of 4,096.

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

	   -Sint     Change the size of the call stack from the default of
		     100 slots.	 Macros take three slots, and nonmacro
		     arguments take one.

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

	   To be effective, the options listed above must appear before any
	   file names and before any -D or -U options.

	   -Dname[=val]
		     Define name as val or as null if val is omitted.

	   -Uname    Undefine name.

    Macro Calls
      Macro calls have the form:

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

      The left parenthesis (() 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



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 m4(1)								       m4(1)




      names consist of alphabetic letters, digits, and underscore (_); the
      first character cannot be a digit.

      Leading unquoted blanks, tabs, and newlines are ignored while
      collecting arguments.  Left and right single quotes (` and ') are used
      to quote strings.	 The value of a quoted string is the string stripped
      of the quotes.

      When a macro name is recognized, its arguments are collected by
      searching 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 which
      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.

    Built-In Macro Names
      m4 makes available the following built-in macros.	 They can be
      redefined, but, once this is done, the original meaning is lost.
      Their values are null unless otherwise stated.

      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.

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

      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 nth 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 equivalent
			to $*, but each argument is quoted (with the current
			quotes).

      defn		Returns the quoted definition of its arguments.	 It
			is useful for renaming macros, especially built-ins.




 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 m4(1)								       m4(1)




      divert		m4 maintains 10 output streams, numbered 0 to 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.

      eval		Evaluates its argument as an arithmetic expression,
			using 32-bit arithmetic.  Operators include +, -, *,
			/, %, ** (exponentiation), bitwise &&amp&amp&, |, ^, and ~,
			relationals, and parentheses.  Octal and hexadecimal
			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.

      hpux		Is a predefined object with a null value.

      ifdef		If the first argument is defined, the value is the
			second argument; otherwise the third.  If there is
			no third argument, the value is null.  The word unix
			is predefined on HP-UX system versions of m4.

      ifelse		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.





 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 m4(1)								       m4(1)




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

      len		Returns the number of characters in its argument.

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

      m4wrap		Argument 1 is pushed back at final EOF; for example:
			m4wrap(`cleanup()')

      maketemp		Fills in a string of XXXXX in its argument with the
			current process ID.

      popdef		Removes current definition of its arguments,
			exposing the previous one, if any.

      pushdef		Similar to 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		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		Executes the HP-UX system command given in the first
			argument.  No value is returned.

      sysval		Is the return code from the last call to syscmd.

      traceoff		Turns off trace globally and for any macros
			specified.  Macros specifically traced by traceon
			can be untraced only by specific calls to traceoff.

      traceon		With no arguments, turns on tracing for all macros
			(including built-ins).	Otherwise, turns on tracing
			for named macros.

      translit		Transliterates the characters in its first argument
			from the set given by the second argument to the set



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 m4(1)								       m4(1)




			given by the third.  No abbreviations are permitted.

      undefine		Removes the definition of the macro named in its
			argument.

      undivert		Causes immediate output of text from diversions
			named as arguments, or all diversions if no
			argument.  Text may be undiverted into another
			diversion.  Undiverting discards the diverted text.

      (XPG4 only.) It is an error to specify an argument containing any
      non-numeric character for the built-in-macros: decr, divert, incr,
      m4exit, substr, undivert, and eval.

 SEE ALSO
      cpp(1), ratfor(1).

 STANDARDS CONFORMANCE
      m4: SVID2, SVID3, XPG2, XPG3, XPG4



































 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000