unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



m4(1)									m4(1)



NAME

  m4 - Preprocesses files, expanding macro definitions

SYNOPSIS

  m4 [-Bnumber]	[-es] [-Hnumber] [-Snumber] [-Tnumber] [-Dmacro] [=value]
  [-Umacro] file... | -

  [XPG4-UNIX]  The m4 command is a macro processor used	as a preprocessor for
  C and	other languages.

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  m4:  XPG4, XPG4-UNIX

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

OPTIONS

  -Bnumber
      [Tru64 UNIX]  Makes number the size of the push-back and parameter col-
      lection buffers (the default is 4096).

  -e  [Tru64 UNIX]  Operates interactively.  Interrupts	are ignored and	the
      output is	not buffered.

  -Hnumber
      [Tru64 UNIX]  Makes number the size of the symbol	table hash array (the
      default is 199).	The size must be a prime number.

  -s  [XPG4-UNIX]  Enables the line sync output	for the	C preprocessor
      (#line...).

  -Snumber
      [Tru64 UNIX]  Makes number the size of the call stack (the default is
      800 slots).  Macros take three slots, and	nonmacro arguments take	one.

  -Tnumber
      [Tru64 UNIX]  Makes number the size of the token buffer (the default is
      512 bytes).

  -Dmacro[=value]
      [XPG4-UNIX]  Defines macro as value.  If value is	not specified, macro
      becomes null.

  -Umacro
      [XPG4-UNIX]  Undefines a built-in	macro or one previously	defined	with
      the -D option.






				     Note

       [XPG4-UNIX]  The	order of options is significant.  If used, the -D or
       -U options must appear after any	other options and before any file
       operands.

OPERANDS

  file
      [XPG4-UNIX]  Pathname of a file to be processed.	If file	is omitted,
      standard input is	used.

  -   [XPG4-UNIX]  Read	standard input.

DESCRIPTION

  [XPG4-UNIX]  You can use m4 to process built-in macros or user-defined mac-
  ros.	Each file is processed in order.  If you do not	specify	a file or if
  you give a dash (-) as a filename, the m4 command reads standard input.  It
  writes the processed macros to standard output.

  [XPG4-UNIX]  Macro calls follow the form:

  macro(argument...)

  [XPG4-UNIX]  The left	parenthesis must immediately follow macro.  If the
  left parenthesis does	not follow the name of a defined macro,	the m4 com-
  mand reads it	as a macro call	with no	arguments.  Macro names	consist	of
  ASCII	alphabetic letters, digits, and	the underscore (_) character.
  Extended characters are not allowed in macro names.  The first character
  cannot be a digit.

  [XPG4-UNIX]  While collecting	arguments, the m4 command ignores unquoted
  leading spaces, tabs,	and newline characters.	 Use single quotes ('')	to
  quote	strings.  The value of a quoted	string is the string with the quota-
  tion marks stripped off.

  [XPG4-UNIX]  When the	m4 command recognizes a	macro, it collects arguments
  by searching for a matching right parenthesis.  If you supply	fewer argu-
  ments	than appear in the macro definition, m4	considers the trailing argu-
  ments	in the definition to be	null.  Macro evaluation	proceeds normally
  during the collection	of the arguments.  All commas or right parentheses
  within the value of a	nested call are	translated literally; they do not
  need an escape character or quotation	marks.	After collecting arguments,
  the m4 command pushes	the value of the macro back onto the input stream and
  scans	again.

  Built-In Macros


  [XPG4-UNIX]  The m4 command contains the following built-in macros.  You
  can redefine them, but they will then	lose their original meanings.  The
  values of these macros are null unless otherwise stated:

  define(macro,new_name)
      [XPG4-UNIX]  Replaces the	macro macro with the value of new_name.	 The
      new_name string can included tokens of the form $n... (where n is	a
      digit).  In this case, each occurrence of	$n in the replacement text is
      replaced by the n-th argument of macro.  The name	of the macro is	$0.
      The null string replaces missing arguments.  The number of arguments
      replaces $#.  A list of all arguments, separated by commas, replaces
      $*.  The $@ acts like $*,	but each argument is quoted with the current
      quotation	character (see the changequote macro).

  undefine(macro...)
      [XPG4-UNIX]  Removes the definition of macro (including those preserved
      using the	pushdef	macro).

  defn(macro...)
      [XPG4-UNIX]  Returns the quoted definition of macro.

  ifdef(macro,true,[false])
      [XPG4-UNIX]  If the first	argument is defined, the value is the second
      argument.	 Otherwise, the	value is the third argument.  If there is no
      third argument, the value	is null.

      [Tru64 UNIX]  Note that the word unix is predefined.

  pushdef(macro,new_name)
      [XPG4-UNIX]  Redefines macro with	new_name as in define, but saves any
      previous definition.

  popdef(macro...)
      [XPG4-UNIX]  Removes the current definition of macro and returns to the
      previous definition, if one existed.

  shift(argument...)
      [XPG4-UNIX]  Returns all but the first argument.	The other arguments
      are quoted and pushed back with commas in	between.  The quoting nulli-
      fies the effect of the extra scan	that is	subsequently performed.

  changequote(left,right)
      [XPG4-UNIX]  The changequote macro sets the begin	and end	symbols. With
      no arguments, the	quote strings are set to the default values (that is,
      `', one grave accent and one apostrophe).	With a single argument,	that
      argument becomes the begin-quote string and the newline character
      becomes the end-quote string. With two arguments,	the first argument
      becomes the begin-quote string and the second argument becomes the
      end-quote	string.	The symbols can	be up to five bytes long.

  changecom[left_comment][,right_comment]
      [XPG4-UNIX]  Changes left	and right comment markers from the default #
      and newline character to left_comment and	right_comment. With no argu-
      ments, the comment mechanism is disabled.	 With one argument, the	left
      marker becomes the parameter and the right marker	becomes	a newline
      character.  With two arguments, both markers are affected.  Comment
      markers can be up	to 5 bytes long.

  divert(number)
      [XPG4-UNIX]  Changes the current output stream to	stream number.	There
      are 10 output streams, numbered 0	to 9.  The final output	is the con-
      catenation of the	streams	in numerical order. Initially, stream zero
      (0) is the current stream.  The m4 command discards output diverted to
      a	stream other than 0 to 9.

  undivert(number...)
      [XPG4-UNIX]  Causes immediate output of text from	the specified diver-
      sions (or	all diversions if there	is no argument).  Text can be
      undiverted into another diversion.  Undiverting discards the diverted
      text.

  divnum
      [XPG4-UNIX]  Returns the value of	the current output stream.

  dnl [XPG4-UNIX]  Reads and discards characters up to and including the next
      newline character.

  ifelse([string1,string2,true,[false]]...)
      [XPG4-UNIX]  If string1 and string2 are the same,	then the value is
      true.  If	they are not and if there are more than	four arguments,	m4
      repeats the process with the additional arguments	(4, 5, 6, and so on).
      Otherwise, the value is either false or null if you provide no value
      for false.

  incr(number)
      [XPG4-UNIX]  Returns the value of	its argument incremented by 1.

  decr(number)
      [XPG4-UNIX]  Returns the value of	its argument decreased by 1.

      "eval(expression[,number1[,number2]])"

      [XPG4-UNIX]  Evaluates its first argument	as an arithmetic expression,
      using 32-bit (long) arithmetic.  The operators you can use include +,
      -, *, /, %, ^ (exponentiation), bitwise &&, |, ~, and ^ relationals, and
      parentheses.

      [XPG4-UNIX]  Octal and hex numbers can be	specified as in	C. The
      optional number1 specifies the radix for the result of the expression.
      The default radix	is 10.	The optional number2 specifies the minimum
      number of	digits in the result.  The default is 1.

  len(string)
      [XPG4-UNIX]  Returns the number of bytes in string.

  dlen(string)
      [Tru64 UNIX]  Returns the	number of displayable characters in string;
      that is, 2-byte extended characters are counted as one displayable
      character.

  index(string1,string2)
      [XPG4-UNIX]  Returns the first position in string1, where	string2
      begins (zero origin), or -1 if the second	argument does not occur.

  substr(string,position,[number]l)
      [XPG4-UNIX]  Returns a substring of string.  The beginning of the	sub-
      string is	selected with position,	and number indicates the length	of
      the substring.  Without number, the substring includes everything	to
      the end of the first string.

  translit(string,from,to)
      [XPG4-UNIX]  Transliterates the characters in string from	the set	given
      by from to the set given by to.  No abbreviations	are permitted.	2-
      byte extended characters are correctly mapped into the corresponding
      replacement characters.

  include(file)
      [XPG4-UNIX]  Returns the contents	of file	or displays an error message
      if it cannot access the file.

  sinclude(file)
      [XPG4-UNIX]  Returns the contents	of file, but it	gives no error mes-
      sage if file is inaccessible.

  syscmd(command)
      [XPG4-UNIX]  Runs	the specified operating	system command.	 No value is
      returned,	but sysval can be used to retrieve the exit value.

  sysval
      [XPG4-UNIX]  Returns the return code from	the last call to syscmd.

  maketemp(...xxxxx)
      [XPG4-UNIX]  Replaces xxxxx in its argument with the current process ID
      number where xxxxx represents any	number of numeric or alphanumeric
      characters.

  m4exit(value)
      [XPG4-UNIX]  Exits from m4 immediately, returning	the specified exit
      value (the default is zero (0)).

  m4wrap(last_macro)
      [XPG4-UNIX]  Sets	or resets last_macro, which is run after reading the
      End-of-File character.  For example: m4wrap(`cleanup()') sets the
      cleanup macro at the end of m4.

  errprint(message)
      [XPG4-UNIX]  Includes message on the diagnostic output file (standard
      error).

  dumpdef([macro...])
      [XPG4-UNIX]  Writes to standard output the current names and defini-
      tions for	the named items	or for all items if no arguments are pro-
      vided.

  traceon(macro)
      [XPG4-UNIX]  Turns on tracing for	macro.	If none	is named, tracing is
      turned on	for all	macro expansions.

  traceoff(macro...)
      [XPG4-UNIX]  Turns off trace globally and	for any	macro specified.
      Macros specifically traced by traceon can	be untraced only by specific
      calls to traceoff.

EXIT STATUS

  0   [XPG4-UNIX]  Successful completion.

  >>0  [XPG4-UNIX]  An error occurred.

  [XPG4-UNIX]  If you use the m4exit macro, the	input file can specify the
  exit value.

EXAMPLES

  To preprocess	a C language program with m4 and compile it, enter:

       m4 prog.m4 >>prog.c
       cc prog.c

ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of m4:

  LANG
      [XPG4-UNIX]  Provides a default value for	the internationalization
      variables	that are unset or null.	If LANG	is unset or null, the
      corresponding value from the default locale is used. If any of the
      internationalization variables contain an	invalid	setting, the utility
      behaves as if none of the	variables had been defined.

  LC_ALL
      [XPG4-UNIX]  If set to a non-empty string	value, overrides the values
      of all the other internationalization variables.

  LC_CTYPE
      [XPG4-UNIX]  Determines the locale for the interpretation	of sequences
      of bytes of text data as characters (for example,	single-byte as
      opposed to multi-byte characters in arguments).

  LC_MESSAGES
      [XPG4-UNIX]  Determines the locale for the format	and contents of	diag-
      nostic messages written to standard error.

  NLSPATH
      [XPG4-UNIX]  Determines the location of message catalogues for the pro-
      cessing of LC_MESSAGES.

SEE ALSO

  Commands:  c89(1), cc(1), cpp(1)

  Standards:  standards(5)