[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 14. Miscellaneous builtin macros

This chapter describes various builtins, that do not really belong in any of the previous chapters.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 14.1 Printing error messages

You can print error messages using `errprint`:

Builtin: errprint (message, …)

  Prints message and the rest of the arguments to standard error, separated by spaces. Standard error is used, regardless of the ``--debugfile'` option (see section Invoking m4).

  The expansion of `errprint` is void. The macro `errprint` is recognized only with parameters.

    errprint(`Invalid arguments to forloop
    ')
    error-->Invalid arguments to forloop
    ⇒
    errprint(`1')errprint(`2',`3
    ')
    error-->12 3
    ⇒

A trailing newline is not printed automatically, so it should be supplied as part of the argument, as in the example. Unfortunately, the exact output of `errprint` is not very portable to other `m4` implementations: POSIX requires that all arguments be printed, but some implementations of `m4` only print the first. Furthermore, some BSD implementations always append a newline for each `errprint` call, regardless of whether the last argument already had one, and POSIX is silent on whether this is acceptable.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 14.2 Printing current location

To make it possible to specify the location of an error, three utility builtins exist:

Builtin: __file__
Builtin: __line__
Builtin: __program__

  Expand to the quoted name of the current input file, the current input line number in that file, and the quoted name of the current invocation of `m4`.

    errprint(__program__:__file__:__line__: `input error
    ')
    error-->m4:stdin:1: input error
    ⇒

Line numbers start at 1 for each file. If the file was found due to the ``-I'` option or `M4PATH` environment variable, that is reflected in the file name. The syncline option (``-s'`, see section Invoking m4), and the ``f'` and ``l'` flags of `debugmode` (see section Controlling debugging output), also use this notion of current file and line. Redefining the three location macros has no effect on syncline, debug, or warning message output. Assume this example is run in the ``m4-1.4.8/checks'` directory of the GNU M4 package, using ``--include=../examples'` in the command line to find the file ``incl.m4'` mentioned earlier:

    define(`foo', ``$0' called at __file__:__line__')
    ⇒
    foo
    ⇒foo called at stdin:2
    include(`incl.m4')
    ⇒Include file start
    ⇒foo called at ../examples/incl.m4:2
    ⇒Include file end
    ⇒

The location of macros invoked during the rescanning of macro expansion text corresponds to the location in the file where the expansion was triggered, regardless of how many newline characters the expansion text contains. As of GNU M4 1.4.8, the location of text wrapped with `m4wrap` (see section Saving text until end of input) is the point at which the `m4wrap` was invoked. Previous versions, however, behaved as though wrapped text came from line 0 of the file "".

    define(`echo', `$@')
    ⇒
    define(`foo', `echo(__line__
    __line__)')
    ⇒
    echo(__line__
    __line__)
    ⇒4
    ⇒5
    m4wrap(`foo
    ')
    ⇒
    foo(errprint(__line__
    __line__
    ))
    error-->8
    error-->9
    ⇒8
    ⇒8
    __line__
    ⇒11
    ^D
    ⇒6
    ⇒6

The `__program__` macro behaves like ``$0'` in shell terminology. If you invoke `m4` through an absolute path or a link with a different spelling, rather than by relying on a `PATH` search for plain ``m4'`, it will affect how `__program__` expands. The intent is that you can use it to produce error messages with the same formatting that `m4` produces internally. It can also be used within `syscmd` (see section Executing simple commands) to pick the same version of `m4` that is currently running, rather than whatever version of `m4` happens to be first in `PATH`. It was first introduced in GNU M4 1.4.6.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 14.3 Exiting from `m4`

If you need to exit from `m4` before the entire input has been read, you can use `m4exit`:

Builtin: m4exit ([code = ``'`])

  Causes `m4` to exit, with exit status code. If code is left out, the exit status is zero. If code cannot be parsed, or is outside the range of 0 to 255, the exit status is one. No further input is read, and all wrapped and diverted text is discarded.

    m4wrap(`This text is lost due to `m4exit'.')
    ⇒
    divert(`1') So is this.
    divert
    ⇒
    m4exit And this is never read.

A common use of this is to abort processing:

Composite: fatal_error (message)

  Abort processing with an error message and non-zero status. Prefix message with details about where the error occurred, and print the resulting string to standard error.

    define(`fatal_error',
           `errprint(__program__:__file__:__line__`: fatal error: $*
    ')m4exit(`1')')
    ⇒
    fatal_error(`this is a BAD one, buster')
    error-->m4:stdin:4: fatal error: this is a BAD one, buster

After this macro call, `m4` will exit with exit status 1. This macro is only intended for error exits, since the normal exit procedures are not followed, e.g., diverted text is not undiverted, and saved text (see section Saving text until end of input) is not reread. (This macro could be made more robust to earlier versions of `m4`. You should try to see if you can find weaknesses and correct them; or see section Answers).

Note that it is still possible for the exit status to be different than what was requested by `m4exit`. If `m4` detects some other error, such as a write error on standard output, the exit status will be non-zero even if `m4exit` requested zero.

If standard input is seekable, then the file will be positioned at the next unread character. If it is a pipe or other non-seekable file, then there are no guarantees how much data `m4` might have read into buffers, and thus discarded.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by root on April, 16 2008 using texi2html 1.76.