What are \immediate & \write18 and how does one use them?

Question

What are \immediate and \write18 and how does one use them? I'd like some examples spanning from basic to advanced scenarios.

Answer 1

Both \immediate and \write are TeX primitives. The \write operation is used to write to a file stream. Like many other things in TeX, file streams are accessed by number (although usually real files are given symbolic names to make life easier). Stream 18 is 'special' as it is not a file at all: instead, it is a way of sending commands to the operating system (shell).

As TeX is a typesetting system, the standard behaviour of \write is to wait until a page is being shipped out before doing anything. That is what you want if the write operation needs things like page numbers. However, there are occasions when you want to write now, which is what \immediate forces. So

\immediate\write18{<stuff>}

means 'send <stuff> to the operating system for execution now'.

There are security issues with allowing arbitrary commands inside a TeX file, and so the standard settings in both TeX Live and MiKTeX turn off full access to \write18. You can turn it on, if you want full access, using latex --shell-escape (or similar) in place of just latex.

As to examples of use, one pretty useful one is to automatically run BibTeX at the start of each LaTeX run by including as the first line

\immediate\write18{bibtex8 --wolfgang \jobname}

The \write operation carries out expansion, and so \jobname here will be converted into the name of the current TeX file.

Recent versions of TeX Live and MiKTeX have a 'restricted \write18' concept which allows a small number of commands to work in \write18 even if --shell-escape is not given. This list is pretty short and features only 'safe' commands (where arbitrary file operations have deliberately been disabled).

Answer 2

PdfTeX has another way to execute system commands which is useful when we need to include the command's output in our document:

\input|"ls xyz.*"

will include the output of the system command enclosed in double quotes. The command line option --shell-escape (or --enable-write18 for MiKTeX) must be given, of course.

When this is used in LaTeX it's still necessary to use the primitive \input, so the construction should be

\makeatletter
\@@input|"ls xyz.*"
\makeatother

This is equivalent to the more complicated

\immediate\write18{ls xyz.* > temp.dat}
\input{temp.dat}

but doesn't require a temporary file. Unfortunately, older versions of XeTeX and LuaTeX don't know about this syntax.

Answer 3

The explanations of Joseph are always good. I give this answer only to show an example: elephant.ps is a picture you can find in the latex companion examples.

% with pdflatex
\documentclass[]{article}
\usepackage{graphicx}

\begin{document}
\immediate\write18{pstopdf elephant.ps}% to get elephant.pdf
\includegraphics[scale=0.5]{elephant.pdf}
\end{document} 

\immediate\write18is very useful to work with gnuplot (see gnuplottex's source), maxima, xcas and bc for examples.