unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

M4(1V)                                                                  M4(1V)



NAME
       m4 - macro language processor

SYNOPSIS
       m4 [ filename ] ...

SYSTEM V SYNOPSIS
       /usr/5bin/m4  [  -es  ]  [  -Bint  ]  [  -Hint  ] [ -Sint ] [ -Tint ] [
       -Dname=val ] [ -Uname ] [ filename ]...

AVAILABILITY
       The System V version of this command is available  with  the  System  V
       software  installation  option.   Refer  to  for  information on how to
       install optional software.

DESCRIPTION
       m4 is a macro processor intended as a front  end  for  Ratfor,  C,  and
       other  languages.  Each of the argument files is processed in order; if
       there are no files, or if a file name is `-',  the  standard  input  is
       read.  The processed text is written on the standard output.

       Macro calls have the form:

              name(argument1[, argument2, ...,] argumentn)

       The  `(' must immediately follow the name of the macro.  If the name of
       a defined macro is not followed by a `(', it is interpreted as  a  call
       of  the macro with no arguments.  Potential macro names consist of let-
       ters, digits, and `_', (underscores) where the first character is not a
       digit.

       Leading  unquoted  SPACE, TAB, and NEWLINE characters 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.

       When a macro name is recognized, the arguments are collected by search-
       ing  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 which 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.

SYSTEM V OPTIONS
       The options and their effects are as follows:

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

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

       -Bint  Change the size of the push-back and argument collection buffers
              from the default of 4,096.

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

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

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

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

       -Dname[=val]
              Define filename to be val or to be NULL in val's absence.

       -Uname Undefine name.

USAGE
   Built-In Macros
       m4  makes  available  the following built-in macros.  They may be rede-
       fined, but once this is done the original meaning is lost.  Their  val-
       ues are NULL unless otherwise stated.

       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.

       undefine    Remove the definition of the macro named in the argument.

       ifdef       If  the  first argument is defined, the value is the second
                   argument, otherwise the third.  If there is no third  argu-
                   ment, the value is NULL.  The word unix is predefined.

       changequote Change  quote characters to the first and second arguments.
                   changequote without arguments restores the original  values
                   (that is, `').

       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  the
                   (digit-string) argument.  Output diverted to a stream other
                   than 0 through 9 is discarded.

       undivert    Display immediate output of text from diversions  named  as
                   arguments,  or  all diversions if no argument.  Text may be
                   undiverted into another  diversion.   Undiverting  discards
                   the diverted text.

       divnum      Return the value of the current output stream.

       dnl         Read  and  discard  characters up to and including the next
                   NEWLINE.

       ifelse      Has three or more arguments.  If the first argument is  the
                   same  string  as  the  second,  then the value is the third
                   argument.  If not, and if there are more  than  four  argu-
                   ments,  the  process  is repeated with arguments 4, 5, 6, 7
                   and so on.  Otherwise, the value is either the last  string
                   not  used  by  the above process, or, if it is not present,
                   NULL.

       incr        Return the value of the argument  incremented  by  1.   The
                   value of the argument is calculated by interpreting an ini-
                   tial digit-string as a decimal number.

       eval        Evaluate the argument as an  arithmetic  expression,  using
                   32-bit  arithmetic.   Operators  include  +,  -, *, /, %, ^
                   (exponentiation); relationals; parentheses.

       len         Return the number of characters in the argument.

       index       Return the position in the first argument where the  second
                   argument begins (zero origin), or -1 if the second argument
                   does not occur.

       substr      Return a substring of the first argument.  The second argu-
                   ment is a zero origin number selecting the first character;
                   the third argument indicates the length of  the  substring.
                   A  missing  third  argument  is taken to be large enough to
                   extend to the end of the first string.

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

       include     Return the contents of the file named in the argument.

       sinclude    Is similar to include, except that it says nothing  if  the
                   file is inaccessible.

       syscmd      Execute the system command given in the first argument.  No
                   value is returned.

       maketemp    Fill in a string of XXXXX in the argument with the  current
                   process ID.

       errprint    Print the argument on the diagnostic output file.

       dumpdef     Print  current  names and definitions, for the named items,
                   or for all if no arguments are given.

SYSTEM V USAGE
       In the System V version of m4, the following built-in macros have added
       capabilities.

   Built-In Macros
       define      `$#' 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).

       changequote Change quote symbols to the  first  and  second  arguments.
                   The symbols may be up to five characters long.

       eval        Additional operators include bitwise `&&', `|', `^' and `~'.
                   Octal, decimal 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.

       The  System  V  version  of m4 makes available the following additional
       built-in macros.

       defn        Return the quoted definition of  the  argument(s).   It  is
                   useful for renaming macros, especially built-ins.

       pushdef     Like define, but saves any previous definition.

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

       shift       Return all but the first argument.  The other arguments are
                   quoted and pushed back with commas in between.  The quoting
                   nullifies the effect of the extra  scan  that  will  subse-
                   quently be performed.

       changecom   Change  left  and  right comment markers from the default #
                   and NEWLINE.  With no arguments, 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        Return the value of the argument decremented by 1.

       sysval      Return code from the last call to syscmd.

       m4exit      Exit immediately from m4.  Argument 1,  if  given,  is  the
                   exit code; the default is 0.

       m4wrap      Argument  1 will be pushed back at final EOF.  For example,
                   `m4wrap("cleanup()")'.

       traceon     With no arguments, turn on tracing for all macros  (includ-
                   ing  built-ins).   Otherwise,  turn  on  tracing  for named
                   macros.

       traceoff    Turn off trace  globally  and  for  any  macros  specified.
                   Macros  specifically traced by traceon can be untraced only
                   by specific calls to traceoff.

SEE ALSO
       cc(1V)

       m4 -- A Macro Processor, in

NOTES
       While the compiler allows 8-bit strings and comments,  8-bits  are  not
       allowed anywhere else.  The cc(1V) command does not generate or support
       8-bit symbol names because, until ANSI C,  non-ASCII  support  was  not
       expected.   The  ANSI C specification now suggests that string literals
       and comments can contain any characters from any character code set.



                               23 September 1987                        M4(1V)