### 9.1 Including named files ¶

There are two builtin macros in `m4` for including files:

Builtin: include (file) ¶
Builtin: sinclude (file) ¶

  Both macros cause the file named file to be read by `m4`. When the end of the file is reached, input is resumed from the previous input file.

  The expansion of `include` and `sinclude` is therefore the contents of file.

  If file does not exist, is a directory, or cannot otherwise be read, the expansion is void, and `include` will fail with an error while `sinclude` is silent. The empty string counts as a file that does not exist.

  The macros `include` and `sinclude` are recognized only with parameters.

    include(`none')
    error→m4:stdin:1: cannot open `none': No such file or directory
    ⇒
    include()
    error→m4:stdin:2: cannot open `': No such file or directory
    ⇒
    sinclude(`none')
    ⇒
    sinclude()
    ⇒

The rest of this section assumes that `m4` is invoked with the `-I` option (see Invoking m4) pointing to the `m4-1.4.19/examples` directory shipped as part of the GNU `m4` package. The file `m4-1.4.19/examples/incl.m4` in the distribution contains the lines:

    $ cat examples/incl.m4
    ⇒Include file start
    ⇒foo
    ⇒Include file end

Normally file inclusion is used to insert the contents of a file into the input stream. The contents of the file will be read by `m4` and macro calls in the file will be expanded:

    $ m4 -I examples
    define(`foo', `FOO')
    ⇒
    include(`incl.m4')
    ⇒Include file start
    ⇒FOO
    ⇒Include file end
    ⇒

The fact that `include` and `sinclude` expand to the contents of the file can be used to define macros that operate on entire files. Here is an example, which defines ‘`bar`’ to expand to the contents of `incl.m4`:

    $ m4 -I examples
    define(`bar', include(`incl.m4'))
    ⇒
    This is `bar':  >>bar<<
    ⇒This is bar:  >>Include file start
    ⇒foo
    ⇒Include file end
    ⇒<<

This use of `include` is not trivial, though, as files can contain quotes, commas, and parentheses, which can interfere with the way the `m4` parser works. GNU `m4` seamlessly concatenates the file contents with the next character, even if the included file ended in the middle of a comment, string, or macro call. These conditions are only treated as end of file errors if specified as input files on the command line.

In GNU `m4`, an alternative method of reading files is using `undivert` (see Undiverting output) on a named file.