(m4.info)Diversions

---

Next: Text handling Prev: File Inclusion Up: Top

---

Enter node , (file) or (file)node

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.

Divert

Diverting output

Undivert

Undiverting output

Divnum

Diversion numbers

Cleardivert

Discarding diverted text