W3cubDocs

\write

Synopsis:

\write number{string}

Write string to the log file, to the terminal, or to a file opened by \openout. For instance, \write6 writes to text stream number 6.

If the following appears in basefile.tex then it opens basefile.jh, writes ‘Hello World!’ and a newline to it, and closes that file.

\newwrite\myfile
\immediate\openout\myfile=\jobname.jh  % \jobname is root file basename
...
\immediate\write\myfile{Hello world!}
...
\immediate\closeout\myfile

The \newwrite allocates a stream number, giving it a symbolic name to make life easier, so that stream \newwrite\myfile\the\myfile produces something like ‘stream 3’. Then \openout associates the stream number with the given file name. TeX ultimately executed \write3 which puts the string in the file.

Typically number is between 0 and 15, because typically LaTeX authors follow the prior example and the number is allocated by the system. If number is outside the range from 0 to 15 or if it is not associated with an open file then LaTeX writes string to the log file. If number is positive then in addition LaTeX writes string to the terminal.

Thus, test \write-1{Hello World!} puts ‘Hello World!’ followed by a newline in the log file. (This is what the \wlog command does; see \wlog). And \write100{Hello World!} puts the same in the log file but also puts ‘Hello World!’ followed by a newline in the terminal output. (But 16, 17, and 18 are special as number; see below.)

In LuaTeX, instead of 16 output streams there are 256 (see TeX engines).

Use \write\@auxout{string} to write to the current .aux file, which is associated with either the root file or with the current include file; and use \write\@mainaux{string} to write to the main .aux. These symbolic names are defined by LaTeX.

By default LaTeX does not write string to the file right away. This is because, for example, you may need \write to save the current page number, but when TeX comes across a \write it typically does not know what the page number is, since it has not yet done the page breaking. So, you use \write in one of three contexts:

\immediate\write\@auxout{string}      %1
\write\@auxout{string}                %2
\protected@write\@auxout{}{string}    %3

1. With the first, LaTeX writes string to the file immediately. Any macros in string are fully expanded (just as in \edef) so to prevent expansion you must use \noexpand, toks, etc., except that you should use # instead of ##).
2. With the second, string is stored on the current list of things (as a TeX “whatsit” item) and kept until the page is shipped out and likewise the macros are unexpanded until \shipout. At \shipout, string is fully expanded.
3. The third, \protected@write, is like the second except that you can use \protect to avoid expansion. The extra first argument allows you to locally insert extra definitions to make more macros protected or to have some other special definition for the write.

As a simple example of expansion with \write, string here contains a control sequence \triplex which we’ve defined to be the text ‘XYZ’:

\newwrite\jhfile
\openout\jhfile=test.jh
\newcommand{\triplex}{XYZ}
\write\jhfile{test \triplex test}

This results in the file test.jh containing the text ‘test XYZtest’ followed by a newline.

The cases where number is 16, 17, or 18 are special. Because of \write’s behavior when number is outside the range from 0 to 15 described above, in Plain TeX \write16 and \write17 were sometimes used to write to the log file and the terminal; however, in LaTeX, the natural way to do that is with \typeout (see \typeout). The \write18 command is even more special; modern TeX systems use it for giving commands to the operating system (see \write18).

Ordinarily \write outputs a single line. You can include a newline with ^^J. Thus, this produces two lines in the log file:

\wlog{Parallel lines have a lot in common.^^JBut they never meet.}

A common case where authors need to write their own file is for answers to exercises, or another situation where you want to write out verbatim, without expanding the macros. CTAN has a number of packages for this; one is answers.

• \write and security		Security.
• \message		Write text to the log file and terminal.
• \wlog		Write text to the log file.
• \write18		Run an operating system command.