Previous: , Up: Input/output   [Contents][Index]


27.5 \write

Synopsis:

\writenumber{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 current file name
  ...
\immediate\write\myfile{Hello world!}
  ...
\immediate\closeout\myfile

The \newwrite allocates a stream number, giving it a symbolic names to make life easier, so that test \newwrite\myfile\the\myfile produces something like ‘test 3’. Then \openout associates the stream number with the given file name. With that, \write3 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).

Write to the current .aux file, which is associated with the main file or with the current include file, using \write\@auxout{string}. Write to the main .aux file using \write\@mainaux{string}.

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

\immediate\write\@auxout{string}
\write\@auxout{string}
\protected@write\@auxout{}{string}

With the first, LaTeX writes string to the file. Any commands in string will be expanded (just as in \edef so that to prevent expansion you should use \noexpand or a toks, except that you should use # instead of ##). With the second, string is stored on the current list of things (as a TeX “whatsit”) and kept until the page is shipped out and likewise the commands are unexpanded until shipout. The third, \protected@write, is like the second except that you can use \protect on fragile commands. The extra first argument allows you to locally insert extra definitions to make more commands be safe or have special definition during the write.

Here string contains a control sequence.

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

This results in the file test.jh containing ‘test XXXtest’ 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. Note that 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. Put in 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.}

The ability to write files raises security issues. If you compiled a downloaded LaTeX file and it overwrote your password file then you would be justifiably troubled. TeX systems by default only allow you to open files for writing that are in the current directory or in a subdirectory. This

\newwrite\jhfile
\openout\jhfile=../test.jh

gives an error like ‘Not writing to ../test.jh (openout_any = p). ! I can't write on file `../test.jh'’. Note that you can get such an error when trying to use commands such as \include{../filename} because LaTeX will try to open ../filename.aux. The simplest solution is to put the included files in the same directory as the master file, or in subdirectories.

A common case where authors want to write a file not already provided by LaTeX is for answers to exercises, or some other situation where you want to write out verbatim, without expanding the commands. CTAN has a number of packages for this; one is answers.


Unofficial LaTeX2e reference manual