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

  man pages->OpenBSD man pages -> m4 (1)              



NAME    [Toc]    [Back]

     m4 - macro language processor

SYNOPSIS    [Toc]    [Back]

     m4  [-d  flags]  [-t   name]   [-o   filename]   [-g]   [-s]
[-Dname[=value]] [-Uname]
        [-I dirname]

DESCRIPTION    [Toc]    [Back]

     The  m4  utility  is a macro processor that can be used as a
front end to
     any language (e.g., C, ratfor, fortran, lex, and yacc).   m4
reads from
     the  standard  input  and  writes  the processed text to the
standard output.

     Macro calls have the form name(argument1[,  argument2,  ...,

     There  cannot  be any space following the macro name and the
open parenthesis
 (`(').  If the macro name is not  followed  by  an  open
parenthesis it
     is processed with no arguments.

     Macro  names  consist  of a leading alphabetic or underscore
possibly followed
 by alphanumeric or underscore characters, e.g.,  valid
macro names
     match the pattern ``[a-zA-Z_][a-zA-Z0-9_]*''.

     In  arguments  to  macros,  leading unquoted space, tab, and
newline (`0)
     characters are ignored.  To  quote  strings,  use  left  and
right single
     quotes  (e.g.,  `  this  is a string with a leading space').
You can change
     the quote characters with the changequote built-in macro.

     Most built-ins don't make any sense without  arguments,  and
hence are not
     recognized as special when not followed by an open parenthesis.

     The options are as follows:

             Define the symbol name to have some value (or NULL).

     -Uname  Undefine the symbol name.

     -I dirname
             Add directory dirname to the include path.

     -d flags
             Set trace flags.  flags may hold the following:

             a       print macro arguments.

             c       print macro expansion over several lines.

             e       print result of macro expansion.

             f       print filename location.

             l       print line number.

             q        quote arguments and expansion with the current quotes.

             t       start with all macros traced.

             x       number macro expansions.

             V       turn on all options.

             By default, trace is set to "eq".

     -o filename
             Send trace output to filename.

     -t macro
             Turn tracing on for macro.

     -g      Activate GNU-m4 compatibility mode.  In  this  mode,
             with   two   empty  parameters  deactivates  quotes,
translit handles
             simple character ranges (e.g., a-z), regular expressions mimic
             emacs  behavior, and the number of diversions is unlimited.

     -s      Output line synchronization directives, suitable for

SYNTAX    [Toc]    [Back]

     m4  provides the following built-in macros.  They may be redefined, losing
     their original meaning.  Return values are null unless  otherwise stated.

                  Calls a built-in by its name, overriding possible redefinitions.

     changecom(startcomment, endcomment)
                  Change the start  and  end  comment  sequences.
The default is
                  the pound sign (`#') and the newline character.
With no arguments
 comments are turned off.   The  maximum
length for a
                  comment marker is five characters.

     changequote(beginquote, endquote)
                  Defines  the  quote symbols to be the first and
second arguments.
  The symbols may be up to  five  characters long.  If
                  no  arguments are given it restores the default
open and
                  close single quotes.

     decr(arg)    Decrements the argument arg by 1.  The argument
arg must be
                  a valid numeric string.

     define(name, value)
                  Define  a new macro named by the first argument
name to have
                  the value of the second argument  value.   Each
occurrence of
                  `$n'  (where  n  is 0 through 9) is replaced by
the n'th argument.
  `$0' is the name of the  calling  macro.
Undefined arguments
 are replaced by a null string.  `$#' is
replaced by
                  the number of arguments; `$*'  is  replaced  by
all arguments
                  comma  separated;  `$@' is the same as `$*' but
all arguments
                  are quoted against further expansion.

     defn(name, ...)
                  Returns the quoted definition  for  each  argument.  This can
                  be  used  to rename macro definitions (even for

     divert(num)  There are 10 output queues (numbered 0-9).   At
the end of
                  processing  m4  concatenates  all the queues in
numerical order
                  to produce the  final  output.   Initially  the
output queue is
                  0.  The divert macro allows you to select a new
output queue
                  (an invalid argument passed  to  divert  causes
output to be

     divnum       Returns the current output queue number.

     dnl           Discard  input  characters up to and including
the next newline.

     dumpdef(name, ...)
                  Prints the names and definitions for the  named
items, or for
                  everything if no arguments are passed.

                  Prints the first argument on the standard error

                  Passes its first argument to a  shell  and  returns the shell's
                  standard  output.   Note  that the shell shares
its standard
                  input and standard error with m4.

     eval(expr)   Computes the first argument  as  an  arithmetic
expression using
 32-bit arithmetic.  Operators are the standard C
                  ternary, arithmetic, logical, shift,  relational, bitwise,
                  and parentheses operators.  You can specify octal, decimal,
                  and hexadecimal numbers as in  C.   The  second
argument (if
                  any) specifies the radix for the result and the
third argument
 (if any) specifies the minimum  number  of
digits in the

     expr(expr)   This is an alias for eval.

     ifdef(name, yes, no)
                  If the macro named by the first argument is defined then return
 the second argument, otherwise the  third.
If there is
                  no third argument, the value is NULL.  The word
"unix" is

     ifelse(a, b, yes, ...)
                  If the first argument a matches the second  argument b then
                  ifelse()  returns  the  third argument yes.  If
the match fails
                  the three arguments are discarded and the  next
three arguments
 are used until there is zero or one arguments left,
                  either this last argument or NULL  is  returned
if no other
                  matches were found.

                  Returns  the  contents of the file specified in
the first argument.
  If the file is not found as  is,  look
through the
                  include  path:  first the directories specified
with -I on the
                  command line,  then  the  environment  variable
M4PATH, as a
                  colon-separated  list  of directories.  Include
aborts with an
                  error message if the file cannot be included.

     incr(arg)    Increments the argument  by  1.   The  argument
must be a valid
                  numeric string.

     index(string, substring)
                  Returns the index of the second argument in the
first argument
 (e.g., index(the quick brown  fox  jumped,
fox) returns
                  16).  If the second argument is not found index
returns -1.

     indir(macro, arg1, ...)
                  Indirectly calls the macro whose name is passed
as the first
                  argument,  with  the remaining arguments passed
as first, ...

     len(arg)     Returns the number of characters in  the  first
argument.  Extra
 arguments are ignored.

                  Immediately  exits with the return value specified by the
                  first argument, 0 if none.

                  Allows you to define what happens at the  final
EOF, usually
                  for        cleanup        purposes       (e.g.,
                  causes the macro cleanup to  be  invoked  after
all other processing
 is done).

                  Invokes  mkstemp(3)  on the first argument, and
returns the
                  modified string.  This can be  used  to  create
unique temporary
 file names.

     paste(file)   Includes the contents of the file specified by
the first argument
 without any  macro  processing.   Aborts
with an error
                  message if the file cannot be included.

     patsubst(string, regexp, replacement)
                  Substitutes  a  regular  expression in a string
with a replacement
 string.  Usual substitution  patterns  apply: an ampersand
  (`&')  is replaced by the string matching
the regular
                  expression.         The        string         `
placed by the corresponding back-reference.

     popdef(arg, ...)
                  Restores  the pushdefed definition for each argument.

     pushdef(macro, def)
                  Takes the same  arguments  as  define,  but  it
saves the definition
   on   a  stack  for  later  retrieval  by

     regexp(string, regexp, replacement)
                  Finds a regular expression in a string.  If  no
further arguments
 are given, it returns the first match position or -1
                  if no match.  If a third argument is  provided,
it returns
                  the  replacement  string, with sub-patterns replaced.

     shift(arg1, ...)
                  Returns all but the first argument, the remaining arguments
                  are  quoted  and pushed back with commas in between.  The
                  quoting nullifies the effect of the extra  scan
that will
                  subsequently be performed.

                  Similar  to  include, except it ignores any errors.

                  Similar to paste(), except it ignores  any  errors.

     substr(string, offset, length)
                  Returns  a  substring  of  the  first  argument
starting at the
                  offset specified by the second argument and the
length specified
 by the third argument.  If no third argument is present
 it returns the rest of the string.

     syscmd(cmd)  Passes the first argument to the shell.   Nothing is returned.

     sysval        Returns the return value from the last syscmd.

     traceon(arg, ...)
                  Enables tracing of  macro  expansions  for  the
given arguments,
                  or for all macros if no argument is given.

     traceoff(arg, ...)
                  Disables  tracing  of  macro expansions for the
given arguments,
 or for all macros if no argument is given.

     translit(string, mapfrom, mapto)
                  Transliterate the characters in the first argument from the
                  set given by the second  argument  to  the  set
given by the
                  third.   You  cannot  use tr(1) style abbreviations.

     undefine(name1, ...)
                  Removes the definition for the macros specified
by its arguments.

     undivert(arg, ...)
                  Flushes  the named output queues (or all queues
if no arguments).

     unix         A pre-defined macro for testing  the  OS  platform.

     __line__     Returns the current file's line number.

     __file__     Returns the current file's name.

STANDARDS    [Toc]    [Back]

     m4 follows the Single Unix 2 specification, along with a few
     taken from gnu-m4.

     The -s option (cpp(1)'s #line directives) is  currently  not
     Flags -I, -d, -t are non-standard.

     The  output  format of tracing and of dumpdef are not specified in any
     standard, are likely to change and should not be relied  upon.  The current
 format of tracing is closely modelled on gnu-m4, to allow autoconf
     to work.

     The built-ins pushdef and popdef handle macro definitions as
a stack.
     However,  define  interacts  with  the stack in an undefined
way.  In this
     implementation, define replaces the top-most definition  only.  Other implementations
  may  erase  all  definitions on the stack instead.

     For portability, one should  not  use  the  macros  builtin,
esycmd, expr,
     indir,  paste,  patsubst,  regexp,  spaste,  unix, __line__,

     All built-ins do expand without arguments in many other  m4.

     Many  other  m4  have  dire size limitations with respect to
buffer sizes.

AUTHORS    [Toc]    [Back]

     Ozan Yigit <oz@sis.yorku.ca> and
     Richard A. O'Keefe <ok@goanna.cs.rmit.OZ.AU>.

     GNU-m4 compatibility extensions by
     Marc Espie <espie@cvs.openbsd.org>.

OpenBSD     3.6                        January      26,      1993
[ Back ]
 Similar pages
Name OS Title
m4 IRIX macro processor
m4 Tru64 GNU m4 macro processor
m4 HP-UX macro processor
m4 Linux GNU macro processor
bc Tru64 Provides a processor for arbitrary-precision arithmetic language
geocustoms HP-UX configure system language on multi-language systems
assign_cpu_to_pset Tru64 Assigns a processor to a processor set
pset_assign_cpu Tru64 Assigns a processor to a processor set
assert FreeBSD expression verification macro
_DIAGASSERT NetBSD expression verification macro
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service