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.18/examples directory shipped as part of the GNU m4 package. The file m4-1.4.18/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 Undivert) on a named file.