# On the basics of writing to & reading from auxiliary files (.aux, .toc, etc.)

Some actions (such as generating the Table of Contents) require two passes of the TeX compiler: during the first pass, some data get written to an auxiliary file, only to be retrieved during the second pass. Here are a few TeX.SE questions that require two-pass solutions:

Two-pass stuff has piqued my interest; I have a few questions:

1. Can I write (append) custom data to an existing auxiliary file (e.g. .aux)? Is that even a good idea? If not, can I generate my own auxiliary file (with a custom extension) to store/retrieve some data?
2. What are good sources for learning the basics of writing to & reading from auxiliary files?
• It's not so hard to write something to the aux file: \immediate\write\@auxout{<something expandable>} or \write\@auxout{<something expandable>}. The aux file is automatically read in at begin document. – clemens May 24 '13 at 11:58
• – Qrrbrbirlbel May 24 '13 at 12:10
• might also want to consider VerbatimOut as provided by fancyvrb. there's a nice discussion in the companion of how it was used for the side-by-side examples in the book. – barbara beeton May 24 '13 at 13:02
• A word of warning: A downside when writing to other files is that often abortion of a compilation can lead to errors the "next time round", forcing you to delete all "half-written" versions of files you created during that run through. This can be quite tedious and while some UIs allow you to automatically delete the aux file, usually they don't check for other files that were created and cause an error in the next run-through (which is imho a plus for writing to the aux file and not create more files ...) – Jonathan Aug 21 '13 at 18:59

You can write to the aux file with

\write\@auxout{hello}


or

\immediate\write\@auxout{hello2}


or

\protected@write\@auxout{}{hello3}


Depending on requirements.

\immediate\write writes to the specified file at that point, expanding the supplied tokens (like \edef) so fragile commands will do the wrong thing.

\write does not write at that point it puts a write node into the current vertical or horizontal list and if that list is shipped out to make a page then the write happens. This is needed to get page numbers correct. (If the write is inside a box and that box is never used on the main page then nothing is written to the file.)

\protected@write is a LaTeX-defined macro that uses \write but arranges that \protect works as required in LaTeX to protect fragile commands. The extra argument unused above allows you to locally insert extra definitions to make more commands be safe or have special definition in the write, see for example the definition of \index or \addtocontents.

It is safe to write to the aux file, however you have to be aware that the file will be read back at least at the begin and end of the document, so you need to write lines that are safe in that context.

If you want to write to your own file then you just need to do

\newwrite\myfile
\immediate\openout\myfile=\jobname.foo


in the preamble and then replace \@auxout by \myfile when writing.

Have a look at the way \tableofcontents or \listoftables or \listoffigures work in latex.ltx or documented in source2e. They basically all use

\def\@starttoc#1{%
\begingroup
\makeatletter
\@input{\jobname.#1}%
\if@filesw
\expandafter\newwrite\csname tf@#1\endcsname
\immediate\openout \csname tf@#1\endcsname \jobname.#1\relax
\fi
\@nobreakfalse
\endgroup}

• Please mention that closing your own file requires \immediate\closeout\myfile. Thanks. – Faheem Mitha Feb 9 '15 at 17:33
• @FaheemMitha you only need to close it explicitly if you are going to input it or write a different file on the same stream, if you do nothing the file will be closed automatically at end document. Also it should be \closeout not \immediate\closeout if there are any non-immediate \write pending. – David Carlisle Oct 2 '18 at 12:39