*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> m4 (1)              



NAME    [Toc]    [Back]

       m4 - Preprocesses files, expanding macro definitions

SYNOPSIS    [Toc]    [Back]

       m4   [-Bnumber]  [-es]  [-Hnumber]  [-Snumber]  [-Tnumber]
       [-Dmacro] [=value] [-Umacro] file... | -

       [XPG4-UNIX]  The m4 command is a macro processor used as a
       preprocessor for C and other languages.

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       m4:  XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

OPTIONS    [Toc]    [Back]

       [Tru64  UNIX]  Makes  number the size of the push-back and
       parameter  collection  buffers  (the  default  is   4096).
       [Tru64   UNIX]  Operates  interactively.   Interrupts  are
       ignored  and  the  output   is   not   buffered.    [Tru64
       UNIX]  Makes  number  the  size  of  the symbol table hash
       array (the default is 199).  The size must be a prime number.
   [XPG4-UNIX]  Enables the line sync output for the C
       preprocessor (#line...).  [Tru64 UNIX]  Makes  number  the
       size of the call stack (the default is 800 slots).  Macros
       take three slots, and nonmacro arguments take one.  [Tru64
       UNIX]  Makes  number  the  size  of  the token buffer (the
       default is  512  bytes).   [XPG4-UNIX]  Defines  macro  as
       value.   If  value  is  not specified, macro becomes null.
       [XPG4-UNIX]  Undefines a built-in macro or one  previously
       defined with the -D option.


       [XPG4-UNIX]  The  order  of  options  is  significant.  If
       used, the -D or -U options must  appear  after  any  other
       options and before any file operands.

OPERANDS    [Toc]    [Back]

       [XPG4-UNIX]  Pathname  of a file to be processed.  If file
       is omitted, standard  input  is  used.   [XPG4-UNIX]  Read
       standard input.

DESCRIPTION    [Toc]    [Back]

       [XPG4-UNIX]  You  can use m4 to process built-in macros or
       user-defined macros.  Each file is processed in order.  If
       you  do  not specify a file or if you give a dash (-) as a
       filename, the m4 command reads standard input.  It  writes
       the processed macros to standard output.

       [XPG4-UNIX]  Macro  calls  follow  the  form:  macro(argument...)

       [XPG4-UNIX]  The left parenthesis must immediately  follow
       macro.   If  the left parenthesis does not follow the name
       of a defined macro, the m4 command reads  it  as  a  macro
       call  with  no  arguments.   Macro  names consist of ASCII
       alphabetic letters, digits, and the underscore (_) character.
   Extended characters are not allowed in macro names.
       The first character cannot be a digit.

       [XPG4-UNIX]  While collecting arguments,  the  m4  command
       ignores unquoted leading spaces, tabs, and newline characters.
  Use single quotes ('') to quote strings.  The value
       of  a quoted string is the string with the quotation marks
       stripped off.

       [XPG4-UNIX]  When the m4 command recognizes  a  macro,  it
       collects  arguments  by  searching  for  a  matching right
       parenthesis.  If you supply fewer arguments than appear in
       the  macro definition, m4 considers the trailing arguments
       in the definition to be null.  Macro  evaluation  proceeds
       normally during the collection of the arguments.  All commas
 or right parentheses within the value of a nested call
       are translated literally; they do not need an escape character
 or quotation marks.  After collecting arguments, the
       m4  command  pushes  the  value of the macro back onto the
       input stream and scans again.

   Built-In Macros    [Toc]    [Back]
       [XPG4-UNIX]  The m4 command contains the following  builtin
 macros.  You can redefine them, but they will then lose
       their original meanings.  The values of these  macros  are
       null  unless  otherwise  stated: [XPG4-UNIX]  Replaces the
       macro macro with the  value  of  new_name.   The  new_name
       string can included tokens of the form $n... (where n is a
       digit).  In this  case,  each  occurrence  of  $n  in  the
       replacement  text  is  replaced  by  the  n-th argument of
       macro.  The name of the macro  is  $0.   The  null  string
       replaces  missing  arguments.   The  number  of  arguments
       replaces $#.  A list of all arguments, separated  by  commas,
  replaces $*.  The $@ acts like $*, but each argument
       is quoted with the current quotation  character  (see  the
       changequote  macro).   [XPG4-UNIX]  Removes the definition
       of macro (including  those  preserved  using  the  pushdef
       macro).   [XPG4-UNIX]  Returns  the  quoted  definition of
       macro.  [XPG4-UNIX]  If the first argument is defined, the
       value is the second argument.  Otherwise, the value is the
       third argument.  If there is no third argument, the  value
       is null.

              [Tru64  UNIX]  Note  that  the  word unix is predefined.
  [XPG4-UNIX]  Redefines macro with  new_name
              as  in  define,  but saves any previous definition.
              [XPG4-UNIX]  Removes  the  current  definition   of
              macro  and  returns  to the previous definition, if
              one  existed.   [XPG4-UNIX]  Returns  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 is subsequently
 performed.  [XPG4-UNIX]  The  changequote
              macro sets the begin and end symbols. With no arguments,
 the quote strings are  set  to  the  default
              values (that is, `', one grave accent and one apostrophe).
 With  a  single  argument,  that  argument
              becomes  the  begin-quote  string  and  the newline
              character becomes the end-quote  string.  With  two
              arguments,  the  first  argument becomes the beginquote
 string and the second  argument  becomes  the
              end-quote  string.  The  symbols  can be up to five
              bytes long.  [XPG4-UNIX]  Changes  left  and  right
              comment  markers  from  the  default  # and newline
              character to left_comment and  right_comment.  With
              no  arguments,  the  comment mechanism is disabled.
              With one argument,  the  left  marker  becomes  the
              parameter  and  the  right marker becomes a newline
              character.  With two arguments,  both  markers  are
              affected.   Comment  markers  can  be up to 5 bytes
              long.   [XPG4-UNIX]  Changes  the  current   output
              stream  to  stream  number.   There  are  10 output
              streams, numbered 0 to 9.  The final output is  the
              concatenation  of  the  streams in numerical order.
              Initially, stream zero (0) is the  current  stream.
              The m4 command discards output diverted to a stream
              other than 0 to 9.   [XPG4-UNIX]  Causes  immediate
              output  of  text  from the specified diversions (or
              all diversions if there is no argument).  Text  can
              be  undiverted into another diversion.  Undiverting
              discards the diverted  text.   [XPG4-UNIX]  Returns
              the   value   of   the   current   output   stream.
              [XPG4-UNIX]  Reads and discards  characters  up  to
              and   including   the   next   newline   character.
              [XPG4-UNIX]  If string1 and string2 are  the  same,
              then  the  value  is  true.  If they are not and if
              there are more than four arguments, m4 repeats  the
              process with the additional arguments (4, 5, 6, and
              so on).  Otherwise, the value is  either  false  or
              null   if   you   provide   no   value  for  false.
              [XPG4-UNIX]  Returns  the  value  of  its  argument
              incremented  by  1.  [XPG4-UNIX]  Returns the value
              of its argument decreased by 1.


              [XPG4-UNIX]  Evaluates its  first  argument  as  an
              arithmetic  expression,  using 32-bit (long) arithmetic.
  The operators you can use include +, -,  *,
              /,  %,  ^  (exponentiation), bitwise &, |, ~, and ^
              relationals, and parentheses.

              [XPG4-UNIX]  Octal and hex numbers can be specified
              as  in  C. The optional number1 specifies the radix
              for the result  of  the  expression.   The  default
              radix  is  10.   The optional number2 specifies the
              minimum  number  of  digits  in  the  result.   The
              default  is  1.  [XPG4-UNIX]  Returns the number of
              bytes in string.  [Tru64 UNIX]  Returns the  number
              of  displayable  characters  in  string;  that  is,
              2-byte extended characters are counted as one  displayable
 character.  [XPG4-UNIX]  Returns the first
              position in string1,  where  string2  begins  (zero
              origin),  or  -1  if  the  second argument does not
              occur.  [XPG4-UNIX]  Returns a substring of string.
              The  beginning  of  the  substring is selected with
              position, and number indicates the  length  of  the
              substring.   Without number, the substring includes
              everything  to  the  end  of  the   first   string.
              [XPG4-UNIX]  Transliterates   the   characters   in
              string from the set given by from to the set  given
              by  to.   No  abbreviations  are permitted.  2-byte
              extended characters are correctly mapped  into  the
              corresponding        replacement        characters.
              [XPG4-UNIX]  Returns the contents of file  or  displays
  an  error  message  if  it cannot access the
              file.  [XPG4-UNIX]  Returns the contents  of  file,
              but it gives no error message if file is inaccessible.
   [XPG4-UNIX]  Runs  the  specified  operating
              system  command.   No value is returned, but sysval
              can  be  used   to   retrieve   the   exit   value.
              [XPG4-UNIX]  Returns  the return code from the last
              call to syscmd.  [XPG4-UNIX]  Replaces xxxxx in its
              argument  with  the current process ID number where
              xxxxx represents any number of numeric or  alphanumeric
 characters.  [XPG4-UNIX]  Exits from m4 immediately,
 returning the specified  exit  value  (the
              default  is zero (0)).  [XPG4-UNIX]  Sets or resets
              last_macro, which is run after reading the  End-ofFile
  character.   For example: m4wrap(`cleanup()')
              sets  the  cleanup  macro  at  the   end   of   m4.
              [XPG4-UNIX]  Includes  message  on  the  diagnostic
              output file (standard error).   [XPG4-UNIX]  Writes
              to  standard  output  the current names and definitions
 for the named items or for all  items  if  no
              arguments   are  provided.   [XPG4-UNIX]  Turns  on
              tracing for macro.  If none is  named,  tracing  is
              turned     on    for    all    macro    expansions.
              [XPG4-UNIX]  Turns off trace globally and  for  any
              macro  specified.   Macros  specifically  traced by
              traceon can be untraced only by specific  calls  to

EXIT STATUS    [Toc]    [Back]

       [XPG4-UNIX]  Successful completion.  [XPG4-UNIX]  An error

       [XPG4-UNIX]  If you use the m4exit macro, the  input  file
       can specify the exit value.

EXAMPLES    [Toc]    [Back]

       To preprocess a C language program with m4 and compile it,
       enter: m4 prog.m4 >prog.c cc prog.c


       The following environment variables affect  the  execution
       of  m4:  [XPG4-UNIX]  Provides  a  default  value  for the
       internationalization variables that are unset or null.  If
       LANG  is  unset  or null, the corresponding value from the
       default locale is used. If any of the internationalization
       variables  contain an invalid setting, the utility behaves
       as  if  none  of   the   variables   had   been   defined.
       [XPG4-UNIX]  If set to a non-empty string value, overrides
       the values of all  the  other  internationalization  variables.
   [XPG4-UNIX]  Determines 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).   [XPG4-UNIX]  Determines  the  locale
       for the format and contents of diagnostic messages written
       to standard error.  [XPG4-UNIX]  Determines  the  location
       of message catalogues for the processing of LC_MESSAGES.

SEE ALSO    [Toc]    [Back]

       Commands:  c89(1), cc(1), cpp(1)

       Standards:  standards(5)

[ Back ]
 Similar pages
Name OS Title
groff_tmac NetBSD macro files in the roff typesetting system
groff_tmac FreeBSD macro files in the roff typesetting system
tmac FreeBSD macro files in the roff typesetting system
mkcatdefs Tru64 Preprocesses a message source file
strccpy IRIX copy strings, compressing or expanding escape codes
m4 HP-UX macro processor
m4 IRIX macro processor
m4 Tru64 GNU m4 macro processor
m4 Linux GNU macro processor
gasp FreeBSD the GNU Assembler Macro Preprocessor
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service