(web2c.info)Shell escapes

---

Next: IPC and TeX Prev: Languages and hyphenation Up: TeX

---

Enter node , (file) or (file)node

4.5 Shell escapes
=================

TeX can execute "shell escapes", that is, arbitrary shell commands.
Although tremendously useful, this also has obvious security
implications.  Therefore, as of TeX Live 2009, a "restricted" mode for
shell escapes is the default mode of operation, which allows executing
only certain commands, as specified in the 'texmf.cnf' configuration
file.

   * Unrestricted shell escapes are allowed if the option
     '--shell-escape' is specified, or if the environment variable or
     config file value 'shell_escape' is set to 't' or 'y' and '1'.

   * Restricted shell escapes are allowed if 'shell_escape' is set to
     'p'.  This is the default.

   * Shell escapes are completely disabled if '--no-shell-escape' is
     specified, or if 'shell_escape' is set to anything else.

   When enabled, the TeX construct to execute a system command is
'\write18{SHELL-COMMAND}'; for example:

     \write18{echo "hello, world"}

   From TeX's point of view, this is a normal '\write' command, and is
therefore subject to the usual TeX expansions.  Also, the system call
either happens during the '\output' routine or right away, according to
the absence or presence of the '\immediate' prefix, as usual for
'\write'.

   The SHELL-COMMAND string is passed to the command shell (via the C
library function 'system').  The output of SHELL-COMMAND is not diverted
anywhere, so it will not appear in the log file, or anywhere but the
terminal output.  The exit status of the system call is also not
available to TeX.

   In unrestricted mode, the argument is simply passed straight to
'system' unaltered.

   In restricted mode, ASCII double quote characters (") should always
be used in the argument to '\write18' where quoting of arguments is
needed, as in the example above.  This is to achieve some measure of
system independence.  On Unix systems, these are replaced with single
quote (') characters to avoid insecure further expansion.  Care is also
taken on Windows to avoid additional expansions (from, e.g., `...`).
Mismatched quotation marks in the command string result in a diagnostic
message in the log file; no execution is performed.

   After quotation processing, if the first word (delimited by a space
or tab) of the command is in the list specified by the
'shell_escape_commands' configuration value, the command is executed.
Otherwise it is not.  In any case, a message is written to the log file.

   The 'shell_escape_commands' value is a comma-separated list of words.
Whitespace is significant, and typically should not be present.  The
default definition looks like this, but with more commands included:

     shell_escape_commands = bibtex,dvips,epstopdf,...,tex

   pdfTeX and luaTeX support reading (via '\input' and '\openin') and
writing (via '\openout') from pipes if the first character is '|'.  The
following command is then treated exactly the same as the argument to
'\write18'.  In these engines, the primitive variable '\pdfshellescape'
is set to 0 if shell escapes are disabled, 1 if they are enabled, and 2
if they are enabled with restrictions.

   The purpose of this feature is to make it possible for TeX documents
to perform useful external actions in the common case of an individual
user running a known document on his or her own machine.  In such
environments as CGI scripts or wikis where the input has to be
considered untrustworthy, shell escapes should be completely disabled.