10 Diverting and undiverting output

Diversions are a way of temporarily saving output. The output of m4 can at any time be diverted to a temporary file, and be reinserted into the output stream, undiverted, again at a later time.

Numbered diversions are counted from 0 upwards, diversion number 0 being the normal output stream. GNU m4 tries to keep diversions in memory. However, there is a limit to the overall memory usable by all diversions taken together (512K, currently). When this maximum is about to be exceeded, a temporary file is opened to receive the contents of the biggest diversion still in memory, freeing this memory for other diversions. When creating the temporary file, m4 honors the value of the environment variable TMPDIR, and falls back to /tmp. Thus, the amount of available disk space provides the only real limit on the number and aggregate size of diversions.

Diversions make it possible to generate output in a different order than the input was read. It is possible to implement topological sorting dependencies. For example, GNU Autoconf makes use of diversions under the hood to ensure that the expansion of a prerequisite macro appears in the output prior to the expansion of a dependent macro, regardless of which order the two macros were invoked in the user’s input file.