xenial (1) m4.1posix.gz

Provided by: manpages-posix_2013a-1_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

NAME

       m4 — macro processor

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 POSIX.1‐2008, Section 12.2, Utility Syntax
       Guidelines,  except  that  the  order  of  the −D and −U options shall be significant, and options can be
       interspersed with operands.

       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 POSIX.1‐2008, 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  white-space  characters
       preceding  each  argument  shall  be  ignored.  All  other  characters,  including  trailing  white-space
       characters, are retained.  <comma> characters enclosed between <left-parenthesis> 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 <comma> characters. The string "$@" is replaced by a list of
       all of the arguments separated by <comma> characters, and each argument is quoted using the current  left
       and right quoting strings. The string "${" produces unspecified behavior.

       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 (backquote) and the right quoting string consists of an acute accent (single-quote); 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  non-null  argument,  that  argument  shall
                 become  the  begin-comment and the <newline> shall become the end-comment string. With two non-
                 null arguments, the first argument  shall  become  the  begin-comment  string  and  the  second
                 argument shall become the end-comment string. The behavior is unspecified if either argument is
                 provided but null. 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, `'). The behavior is unspecified if
                 there is a single argument or either argument is null. With two non-null 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.  The behavior is
                 unspecified if decr is not immediately followed by a <left-parenthesis>.

       define    The second argument shall become the defining text  of  the  macro  whose  name  is  the  first
                 argument. It is unspecified whether the define macro deletes all prior definitions of the macro
                 named by its first argument or preserves all but the current  definition  of  the  macro.   The
                 behavior is unspecified if define is not immediately followed by a <left-parenthesis>.

       defn      The  defining  text of the defn macro shall be the quoted definition (using the current quoting
                 strings) of its arguments. The behavior is unspecified if defn is not immediately followed by a
                 <left-parenthesis>.

       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  with a negative number shall be
                 discarded. Behavior is implementation-defined if a stream number larger than 9 is specified. 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. The behavior is unspecified  if
                 errprint is not immediately followed by a <left-parenthesis>.

       eval      The  eval  macro  shall  evaluate  its first argument as an arithmetic expression, using signed
                 integer arithmetic with at least 32-bit precision. At least the following C-language  operators
                 shall  be  supported,  with  precedence,  associativity,  and  behavior as described in Section
                 1.1.2.1, Arithmetic Precision and Operations:

                     ()
                     unary +
                     unary 
                     ~

                     !
                     binary *
                     /
                     %
                     binary +
                     binary −
                     <<
                     >>
                     <
                     <=
                     >
                     >=
                     ==
                     !=
                     binary &
                     ^
                     |
                     &&
                     ||

                 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; if the argument is blank or
                 unspecified, the default is 10. Behavior is unspecified if the radix falls outside the range  2
                 to  36,  inclusive.  The third argument, if specified, sets the minimum number of digits in the
                 result. Behavior is unspecified if the third argument is less than zero. It shall be  an  error
                 to  specify the second or third argument containing any non-numeric characters. The behavior is
                 unspecified if eval is not immediately followed by a <left-parenthesis>.

       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. The behavior is unspecified if ifdef is not immediately followed  by  a  <left-
                 parenthesis>.

       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. The behavior is unspecified if ifelse  is  not  immediately  followed  by  a  <left-
                 parenthesis>.

       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.  The  behavior  is  unspecified  if
                 include is not immediately followed by a <left-parenthesis>.

       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.   The  behavior  is
                 unspecified if incr is not immediately followed by a <left-parenthesis>.

       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.   The  behavior  is unspecified if index is not immediately
                 followed by a <left-parenthesis>.

       len       The defining text of the len macro shall be the length (as a string)  of  the  first  argument.
                 The behavior is unspecified if len is not immediately followed by a <left-parenthesis>.

       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. The behavior is unspecified if m4wrap  is  not  immediately  followed  by  a  <left-
                 parenthesis>.

       maketemp  The  defining  text shall be the first argument, with any trailing 'X' characters replaced with
                 the current process ID as a string.  The behavior is unspecified if maketemp is not immediately
                 followed by a <left-parenthesis>.

       mkstemp   The  first  argument shall be taken as a template for creating an empty file, with trailing 'X'
                 characters replaced with characters from the portable filename character set. The  behavior  is
                 unspecified  if  the first argument does not end in at least six 'X' characters. If a temporary
                 file is successfully created, then the defining text of the macro shall be the name of the  new
                 file.   The user ID of the file shall be set to the effective user ID of the process. The group
                 ID of the file shall be set to the group ID of the file's parent directory or to the  effective
                 group  ID  of the process. The file access permission bits are set such that only the owner can
                 both read and write the file, regardless of the current umask of the process. If a  file  could
                 not  be  created,  the  defining  text  of the macro shall be the empty string. The behavior is
                 unspecified if mkstemp is not immediately followed by a <left-parenthesis>.

       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.
                 The behavior is unspecified if popdef is not immediately followed by a <left-parenthesis>.

       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. The behavior is
                 unspecified if pushdef is not immediately followed by a <left-parenthesis>.

       shift     The defining text for the shift macro shall be a comma-separated list of its  arguments  except
                 the  first  one. Each argument shall be quoted using the current quoting strings.  The behavior
                 is unspecified if shift is not immediately followed by a <left-parenthesis>.

       sinclude  The sinclude macro shall be equivalent to the include macro, except that it  shall  not  be  an
                 error  if the file is inaccessible.  The behavior is unspecified if sinclude is not immediately
                 followed by a <left-parenthesis>.

       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.  The behavior is unspecified if substr is not  immediately  followed  by  a
                 <left-parenthesis>.

       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. The string result shall not be rescanned for macros
                 while  setting  the  defining text. No output redirection shall be performed by the m4 utility.
                 The exit status value from the command can be retrieved using the sysval macro. The behavior is
                 unspecified if syscmd is not immediately followed by a <left-parenthesis>.

       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. If no replacement character is specified for some source character because the second
                 argument is longer than the third argument, that character shall  be  deleted  from  the  first
                 argument  in translit's defining text. The behavior is unspecified if the '−' character appears
                 within the second or third argument anywhere besides the first or last character. The  behavior
                 is  unspecified  if  the  same  character  appears  more  than once in the second argument. The
                 behavior is unspecified if translit is not immediately followed by a <left-parenthesis>.

       undefine  The undefine macro shall delete all definitions (including those preserved  using  the  pushdef
                 macro)  of  the  macros  named by its arguments. The behavior is unspecified if undefine is not
                 immediately followed by a <left-parenthesis>.

       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.
                 The behavior is unspecified if an argument contains 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.

       Since   eval   defers   to  the  ISO C  standard,  some  operations  have  undefined  behavior.  In  some
       implementations, division or remainder by zero cause a fatal signal, even if the division occurs  on  the
       short-circuited  branch  of  "&&"  or  "||".   Any operation that overflows in signed arithmetic produces
       undefined behavior. Likewise, using the shift operators with a shift amount  that  is  not  positive  and
       smaller than the precision is undefined, as is shifting a negative number to the right. Historically, not
       all implementations obeyed C-language precedence rules: '~' and '!'  were lower than '=='; '==' and  '!='
       were  not  lower  than '<'; and '|' was not lower than '^'; the liberal use of "()" can force the desired
       precedence even with these non-compliant implementations. Furthermore, some  traditional  implementations
       treated '^' as an exponentiation operator, although most implementations now use "**" as an extension for
       this purpose.

       When a macro has been multiply defined via the pushdef macro, it is unspecified whether the define  macro
       will alter only the most recent definition (as though by popdef and pushdef), or replace the entire stack
       of definitions with a single definition (as though by undefine and  pushdef).   An  application  desiring
       particular behavior for the define macro in this case can redefine it accordingly.

       Applications  should  use  the  mkstemp  macro  instead  of  the  obsolescent maketemp macro for creating
       temporary files.

EXAMPLES

       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

RATIONALE

       Historic System V-based behavior treated "${" in a macro definition as two literal  characters.  However,
       this  sequence  is  left unspecified so that implementations may offer extensions such as "${11}" meaning
       the eleventh positional parameter. Macros can still be defined with appropriate uses of nested quoting to
       result in a literal "${" in the output after rescanning removes the nested quotes.

       In  the translit built-in, historic System V-based behavior treated '−' as a literal; GNU behavior treats
       it as a range. This version of the standard allows either behavior.

FUTURE DIRECTIONS

       None.

SEE ALSO

       c99

       The Base Definitions volume of POSIX.1‐2008, Chapter 8,  Environment  Variables,  Section  12.2,  Utility
       Syntax Guidelines

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications  Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc
       and The Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any  typographical  or formatting errors that appear in this page are most likely to have been introduced
       during  the  conversion  of  the  source  files  to  man  page  format.  To  report  such   errors,   see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .