Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1‎ > ‎

m4


NAME
     m4 - macro processor

SYNOPSIS
     /usr/ccs/bin/m4 [-e]  [-s]  [-B int]  [-H int]  [-S int]  [-
     T int] [ -Dname [=val]] ... [-U name] ... [file...]

     /usr/xpg4/bin/m4 [-e] [-s]  [-B int]  [-H int]  [-S int]  [-
     T int] [ -Dname [ ...=val]] [-U name] ... [file...]

DESCRIPTION
     The m4 utility is a macro processor intended as a front  end
     for  C, assembler, and other languages. Each of the argument
     files is processed in order. If there are no files, or if  a
     file is -, the standard input is read. The processed text is
     written on the standard output. Note: m4 cannot include more
     than  nine  nested files and will write a diagnostic message
     if that number is exceeded.

  Macro Syntax
     Macro calls have the form:

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

     The open parenthesis character, (, 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  names  consist  of
     alphanumeric characters and underscore (_), where the  first
     character is not a digit.

     Leading unquoted blanks,  <TAB>s, and NEWLINEs  are  ignored
     while collecting arguments. Left and right single quotes are
     used to quote strings. The value of a quoted string  is  the
     string stripped of the quotes.

  Macro Processing
     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 that 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.

OPTIONS
     The options and their effects are as follows:


     -Bint    Changes the size of the push-back and argument col-
              lection buffers from the default of  4,096.



     -e       Operates interactively. Interrupts are ignored  and
              the output is unbuffered.



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



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



     -Sint    Changes the size of the call stack from the default
              of   100slots.  Macros  take  three slots, and non-
              macro arguments take one.



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



     To be effective, the above flags must appear before any file
     names and before any -D or -U flags:

     -D name[=val]   Defines name to val  or  to  NULL  in  val's
                     absence.



     -Uname          Undefines name.



OPERANDS
     The following operand is supported:

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



USAGE
     The m4 utility makes available the following  built-in  mac-
     ros.  These  macros  may be redefined, but once this is done
     the original meaning is lost. Their values are  NULL  unless
     otherwise stated.

     changequote     Change quote symbols to the first and second
                     arguments.  The  symbols  may  be up to five
                     characters long. changequote  without  argu-
                     ments restores the original values (that is,
                     `').



     changecom       Change left and right comment  markers  from
                     the  default  #  and  NEWLINE. With no argu-
                     ments, 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.



     decr            Returns the value  of  its  argument  decre-
                     mented 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 n-th 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 like $*, but each argument is
                     quoted (with the current quotes).



     defn            Returns  the  quoted   definition   of   its
                     argument(s).  It is useful for renaming mac-
                     ros, especially built-ins.



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



     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.



  /usr/ccs/bin/m4
     eval            Evaluates  its  argument  as  an  arithmetic
                     expression,   using   32-bit  signed-integer
                     arithmetic. The following operators are sup-
                     ported: parentheses, unary -, unary +, !, ~,
                     *, /, %, +, -, relationals,  bitwise  &,  |,
                     &&,  and  ||.   Octal and hex 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.



  /usr/xpg4/bin/m4
     eval            Evaluates  its  argument  as  an  arithmetic
                     expression,   using   32-bit  signed-integer
                     arithmetic. The following operators are sup-
                     ported: parentheses, unary -, unary +, !, ~,
                     *, /, %, +, -, <<, >>, relationals,  bitwise
                     &,   |,   &&,   and   ||.    Precedence  and
                     associativity are as in  C.  Octal  and  hex
                     numbers  may  also be specified as in C. The
                     second argument specifies the radix for  the
                     result;  the  default is 10. The third argu-
                     ment may be  used  to  specify  the  minimum
                     number of digits in the result.



     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.



     ifelse          This macro has three or more  arguments.  If
                     the first argument is the same string as the
                     second, then the value is  the  third  argu-
                     ment.  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  incre-
                     mented  by  1.  The value of the argument is
                     calculated  by   interpreting   an   initial
                     digit-string as a decimal number.



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



     len             Returns the  number  of  characters  in  its
                     argument.




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



     m4wrap          Argument 1 will be pushed back at final EOF.
                     Example: m4wrap(`cleanup()')



     maketemp        Fills in a string of "X" characters  in  its
                     argument with the current process ID.



     popdef          Removes   current    definition    of    its
                     argument(s),  exposing  the previous one, if
                     any.



     pushdef         Like define, but saves any previous  defini-
                     tion.



     shift           Returns all  but  its  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 will
                     subsequently be performed.



     sinclude        This macro is identical to  include,  except
                     that it says nothing if the file is inacces-
                     sible.



     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 sub-
                     string. A missing third argument is taken to
                     be  large enough to extend to the end of the
                     first string.




     syscmd          This macro executes the command given in the
                     first argument. No value is returned.



     sysval          This macro is the return code from the  last
                     call to syscmd.



     translit        Transliterates the characters in  its  first
                     argument  from  the  set given by the second
                     argument to the set given by the  third.  No
                     abbreviations are permitted.



     traceon         This macro with no arguments, turns on trac-
                     ing  for  all  macros (including built-ins).
                     Otherwise, turns on tracing for  named  mac-
                     ros.



     traceoff        Turns off trace globally and for any  macros
                     specified.



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



     undivert        This macro causes immediate output  of  text
                     from  diversions  named as arguments, or all
                     diversions  if  no  argument.  Text  may  be
                     undiverted into another diversion. Undivert-
                     ing discards the diverted text.



EXAMPLES
     Example 1: Examples of m4 files

     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

ENVIRONMENT VARIABLES
     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution of m4: LANG, LC_ALL,
     LC_CTYPE, LC_MESSAGES, and NLSPATH.

EXIT STATUS
     The following exit values are returned:

     0        Successful completion.



     >0       An error occurred



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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

  /usr/ccs/bin/m4
     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|


  /usr/xpg4/bin/m4
     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWxcu4                    |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|


SEE ALSO
     as(1), attributes(5), environ(5), standards(5)










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments