Man Linux: Main Page and Category List

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 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,    Internationalization
              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 internationalization 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 arguments and input files).

       LC_MESSAGES
              Determine the locale that should be used to  affect  the  format
              and contents of diagnostic 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 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  integer  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 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  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 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 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 ofVERis "VER".
              ifdef(VER, "VER" is defined to be VER., VER is not defined.)
              ifelse(VER, 1, "VER" isVER.)
              ifelse(VER, 2, "VER" isVER., "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 original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .