Unix/Linux Go Back    


SuSE 11.3 - man page for m4 (suse section 1P)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


M4(1P)				    POSIX Programmer's Manual				   M4(1P)

PROLOG
       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME
       m4 - macro processor (DEVELOPMENT)

SYNOPSIS
       m4 [-s][-D name[=val]]...[-U name]... file...

DESCRIPTION
       The  m4	utility is a macro processor that shall read one or more text files, process them
       according to their included macro statements, and write the results to standard output.

OPTIONS
       The m4 utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001,  Sec-
       tion 12.2, Utility Syntax Guidelines, except that the order of the -D and -U options shall
       be significant.

       The following options shall be supported:

       -s     Enable line synchronization output for the c99 preprocessor phase (that  is,  #line
	      directives).

       -D  name[=val]

	      Define name to val or to null if = val is omitted.

       -U  name
	      Undefine name.

OPERANDS
       The following operand shall be supported:

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

STDIN
       The standard input shall be a text file that is used if no file operand is given, or if it
       is '-' .

INPUT FILES
       The input file named by the file operand shall be a text file.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of m4:

       LANG   Provide  a  default  value for the internationalization variables that are unset or
	      null. (See the Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Inter-
	      nationalization Variables for the precedence of internationalization variables used
	      to determine the values of locale categories.)

       LC_ALL If set to a non-empty string value, override the values of all the  other  interna-
	      tionalization variables.

       LC_CTYPE
	      Determine  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  argu-
	      ments and input files).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic messages written to standard error.

       NLSPATH
	      Determine the location of message catalogs for the processing of LC_MESSAGES .

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       The standard output shall be the same as the input files, after being processed for  macro
       expansion.

STDERR
       The standard error shall be used to display strings with the errprint macro, macro tracing
       enabled by the traceon macro, the defined text for macros written by the dumpdef macro, or
       for diagnostic messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       The  m4	utility  shall	compare each token from the input against the set of built-in and
       user-defined macros. If the token matches the name of a macro, then  the  token	shall  be
       replaced  by  the  macro's  defining text, if any, and rescanned for matching macro names.
       Once no portion of the token matches the name of a macro, it shall be written to  standard
       output.	Macros	may have arguments, in which case the arguments shall be substituted into
       the defining text before it is rescanned.

       Macro calls have the form:

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

       Macro names shall consist of letters, digits, and underscores, where the  first	character
       is not a digit. Tokens not of this form shall not be treated as macros.

       The application shall ensure that the left parenthesis immediately follows the name of the
       macro. If a token matching the name of a macro is not followed by a left  parenthesis,  it
       is handled as a use of that macro without arguments.

       If  a  macro name is followed by a left parenthesis, its arguments are the comma-separated
       tokens between the left parenthesis and the matching right parenthesis. Unquoted  <blank>s
       and  <newline>s	preceding each argument shall be ignored. All other characters, including
       trailing <blank>s and <newline>s, are retained.	Commas enclosed between  left  and  right
       parenthesis characters do not delimit arguments.

       Arguments  are  positionally  defined and referenced. The string "$1" in the defining text
       shall be replaced by the first argument. Systems shall support at  least  nine  arguments;
       only  the  first  nine  can  be referenced, using the strings "$1" to "$9", inclusive. The
       string "$0" is replaced with the name of the macro. The string "$#"  is	replaced  by  the
       number of arguments as a string. The string "$*" is replaced by a list of all of the argu-
       ments, separated by commas.  The string "$@" is replaced by a list of all of the arguments
       separated  by commas, and each argument is quoted using the current left and right quoting
       strings.

       If fewer arguments are supplied than are in the macro definition,  the  omitted	arguments
       are  taken  to  be null. It is not an error if more arguments are supplied than are in the
       macro definition.

       No special meaning is given to any characters enclosed between  matching  left  and  right
       quoting	strings,  but  the quoting strings are themselves discarded. By default, the left
       quoting string consists of a grave accent ( '`' ) and the right quoting string consists of
       an acute accent ( '" ); see also the changequote macro.

       Comments  are written but not scanned for matching macro names; by default, the begin-com-
       ment string consists of the number sign character and the end-comment string consists of a
       <newline>. See also the changecom and dnl macros.

       The m4 utility shall make available the following built-in macros.  They can be redefined,
       but once this is done the original meaning is lost. Their values shall be null unless oth-
       erwise  stated.	In  the descriptions below, the term defining text refers to the value of
       the macro: the second argument to the define macro, among other	things.  Except  for  the
       first argument to the eval macro, all numeric arguments to built-in macros shall be inter-
       preted as decimal values. The string values produced as the defining  text  of  the  decr,
       divnum,	incr,  index,  len, and sysval built-in macros shall be in the form of a decimal-
       constant as defined in the C language.

       changecom
	      The changecom macro shall set the begin-comment and end-comment  strings.  With  no
	      arguments,  the  comment	mechanism shall be disabled. With a single argument, that
	      argument shall become the begin-comment string and the <newline> shall  become  the
	      end-comment  string. With two arguments, the first argument shall become the begin-
	      comment string and the second argument shall become the end-comment string. Systems
	      shall support comment strings of at least five characters.

       changequote
	      The  changequote	macro  shall  set  the begin-quote and end-quote strings. With no
	      arguments, the quote strings shall be set to the default values (that is, `'). With
	      a  single argument, that argument shall become the begin-quote string and the <new-
	      line> shall become the end-quote string. With two  arguments,  the  first  argument
	      shall  become  the begin-quote string and the second argument shall become the end-
	      quote string. Systems shall support quote strings of at least five characters.

       decr   The defining text of the decr macro shall be its first argument decremented  by  1.
	      It shall be an error to specify an argument containing any non-numeric characters.

       define The  second  argument shall become the defining text of the macro whose name is the
	      first argument.

       defn   The defining text of the defn macro shall be the quoted definition (using the  cur-
	      rent quoting strings) of its arguments.

       divert The  m4  utility maintains nine temporary buffers, numbered 1 to 9, inclusive. When
	      the last of the input has been processed, any output that has been placed in  these
	      buffers  shall  be written to standard output in buffer-numerical order. The divert
	      macro shall divert future output to the buffer specified by its argument.  Specify-
	      ing  no argument or an argument of 0 shall resume the normal output process. Output
	      diverted to a stream other than 0 to 9 shall be discarded. It shall be an error  to
	      specify an argument containing any non-numeric characters.

       divnum The  defining  text  of  the divnum macro shall be the number of the current output
	      stream as a string.

       dnl    The dnl macro shall cause m4 to discard all input characters up  to  and	including
	      the next <newline>.

       dumpdef
	      The  dumpdef  macro  shall write the defined text to standard error for each of the
	      macros specified as arguments, or, if no arguments are specified, for all macros.

       errprint
	      The errprint macro shall write its arguments to standard error.

       eval   The eval macro shall evaluate its first argument as an arithmetic expression, using
	      32-bit  signed  integer  arithmetic.  All of the C-language operators shall be sup-
	      ported, except for:

	      []
	      ->
	      ++
	      --
	      (type)
	      unary *
	      sizeof,
	      .
	      ?:
	      unary &

       and all assignment operators. It shall be an error to  specify  any  of	these  operators.
       Precedence  and	associativity  shall  be  as in the ISO C standard. Systems shall support
       octal and hexadecimal numbers as in the ISO C standard. The second argument, if specified,
       shall  set the radix for the result; the default is 10.	The third argument, if specified,
       sets the minimum number of digits in the result. It shall be an error to specify the  sec-
       ond or third argument containing any non-numeric characters.

       ifdef  If the first argument to the ifdef macro is defined, the defining text shall be the
	      second argument. Otherwise, the defining text shall be the third argument, if spec-
	      ified, or the null string, if not.

       ifelse The  ifelse macro takes three or more arguments. If the first two arguments compare
	      as equal strings (after macro expansion of both arguments), the defining text shall
	      be  the  third argument. If the first two arguments do not compare as equal strings
	      and there are three arguments, the defining text shall be null. If  the  first  two
	      arguments do not compare as equal strings and there are four or five arguments, the
	      defining text shall be the fourth argument. If the first two arguments do not  com-
	      pare  as	equal  strings and there are six or more arguments, the first three argu-
	      ments shall be discarded and processing shall restart with the remaining arguments.

       include
	      The defining text for the include macro shall be the contents of the file named  by
	      the first argument. It shall be an error if the file cannot be read.

       incr   The  defining  text of the incr macro shall be its first argument incremented by 1.
	      It shall be an error to specify an argument containing any non-numeric characters.

       index  The defining text of the index macro shall be the first character  position  (as	a
	      string)  in  the	first argument where a string matching the second argument begins
	      (zero origin), or -1 if the second argument does not occur.

       len    The defining text of the len macro shall be the length (as a string) of  the  first
	      argument.

       m4exit Exit  from the m4 utility. If the first argument is specified, it is the exit code.
	      The default is zero. It shall be an error to specify  an	argument  containing  any
	      non-numeric characters.

       m4wrap The  first  argument shall be processed when EOF is reached. If the m4wrap macro is
	      used multiple times, the arguments specified shall be processed  in  the	order  in
	      which the m4wrap macros were processed.

       maketemp
	      The  defining  text  shall  be the first argument, with any trailing 'X' characters
	      replaced with the current process ID as a string.

       popdef The popdef macro shall delete the current definition of  its  arguments,	replacing
	      that  definition	with  the  previous one.  If there is no previous definition, the
	      macro is undefined.

       pushdef
	      The pushdef macro shall be equivalent to the define macro with the  exception  that
	      it  shall  preserve  any	current  definition for future retrieval using the popdef
	      macro.

       shift  The defining text for the shift macro shall be all of its arguments except for  the
	      first one.

       sinclude
	      The  sinclude  macro shall be equivalent to the include macro, except that it shall
	      not be an error if the file is inaccessible.

       substr The defining text for the substr macro shall be the substring of the first argument
	      beginning  at  the zero-offset character position specified by the second argument.
	      The third argument, if specified, shall be the number of characters to  select;  if
	      not specified, the characters from the starting point to the end of the first argu-
	      ment shall become the defining text. It shall not be an error to specify a starting
	      point  beyond the end of the first argument and the defining text shall be null. It
	      shall be an error to specify an argument containing any non-numeric characters.

       syscmd The syscmd macro shall interpret its first argument as a shell  command  line.  The
	      defining	text  shall  be  the string result of that command. No output redirection
	      shall be performed by the m4 utility. The exit status value from the command can be
	      retrieved using the sysval macro.

       sysval The  defining  text of the sysval macro shall be the exit value of the utility last
	      invoked by the syscmd macro (as a string).

       traceon
	      The traceon macro shall enable tracing for the macros specified as  arguments,  or,
	      if no arguments are specified, for all macros. The trace output shall be written to
	      standard error in an unspecified format.

       traceoff
	      The traceoff macro shall disable tracing for the macros specified as arguments, or,
	      if no arguments are specified, for all macros.

       translit
	      The  defining  text  of  the  translit macro shall be the first argument with every
	      character that occurs in the second argument replaced with the corresponding  char-
	      acter from the third argument.

       undefine
	      The  undefine  macro  shall delete all definitions (including those preserved using
	      the pushdef macro) of the macros named by its arguments.

       undivert
	      The undivert macro shall cause immediate output of any text  in  temporary  buffers
	      named as arguments, or all temporary buffers if no arguments are specified. Buffers
	      can be undiverted into other temporary buffers. Undiverting shall discard the  con-
	      tents of the temporary buffer. It shall be an error to specify an argument contain-
	      ing any non-numeric characters.

EXIT STATUS
       The following exit values shall be returned:

	0     Successful completion.

       >0     An error occurred

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

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       The defn macro is useful for renaming macros, especially built-ins.

EXAMPLES
       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

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       c99

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					   M4(1P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:39 PM.