Man Pages

m4(1p) - phpMan m4(1p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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, Section 12.2, Utility Syn-
       tax 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, Internationalization Variables for the prece-
              dence 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 internationalization variables.

       LC_CTYPE
              Determine  the locale for the interpretation of sequences of bytes of text data as characters (for exam-
              ple, single-byte as opposed to multi-byte characters in arguments and input files).

       LC_MESSAGES
              Determine the locale that should be used to affect the format and contents of diagnostic messages  writ-
              ten 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  with-
       out 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 arguments,
       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-comment 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 otherwise 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 interpreted 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 <newline> 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 current 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.  Specifying  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  inte-
              ger arithmetic.  All of the C-language operators shall be supported, except for:


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

       and  all  assignment operators. It shall be an error to specify any of these operators. Precedence and associa-
       tivity 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
       second 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 specified, 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  compare  as  equal
              strings and there are six or more arguments, the first three arguments 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  cur-
              rent 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 argument 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 character 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 contents of the temporary buffer. It shall be an error to specify
              an argument containing 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, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, the original IEEE and The Open Group Standard is the referee  document.  The  original  Standard  can  be
       obtained online at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                               M4(1P)