<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="reference.luasandbox.differences" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Differences from Standard Lua</title>

 <para>
  LuaSandbox provides a sandboxed environment which differs in some ways from standard Lua 5.1.
 </para>

 <simplesect xml:id="reference.luasandbox.differences.unavailable">
  <title>Features that are not available</title>
  <para>
   <itemizedlist>
    <listitem>
     <para>
      <literal>dofile()</literal>, <literal>loadfile()</literal>, and the <literal>io</literal> package, as they allow direct filesystem access. If needed, filesystem access should be done via PHP callbacks.
     </para>
    </listitem>
    <listitem>
     <para>
      The <literal>package</literal> package, including <literal>require()</literal> and <literal>module()</literal>, as it depends heavily on direct filesystem access. A pure-Lua rewrite such as that used in the MediaWiki Scribunto extension may be used instead.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>load()</literal> and <literal>loadstring()</literal>, to allow for static analysis of Lua code.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>print()</literal>, since it outputs to standard output. If needed, output should be done via PHP callbacks.
     </para>
    </listitem>
    <listitem>
     <para>
      Most of the <literal>os</literal> package, as it allows manipulation of the process and executing of other processes.
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <para>
         <literal>os.clock()</literal>, <literal>os.date()</literal>, <literal>os.difftime()</literal>, and <literal>os.time()</literal> remain available.
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </listitem>
    <listitem>
     <para>
      Most of the <literal>debug</literal> package, as it allows manipulation of Lua state and metadata in ways that can break sandboxing.
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <para>
         <literal>debug.traceback()</literal> remains available.
         </para>
       </listitem>
      </itemizedlist>
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>string.dump()</literal>, as it may expose internal data.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>collectgarbage()</literal>, <literal>gcinfo()</literal>, and the <literal>coroutine</literal> package have not been reviewed for security.
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </simplesect>

 <simplesect xml:id="reference.luasandbox.differences.modified">
  <title>Features that have been modified</title>
  <para>
   <itemizedlist>
    <listitem>
     <para>
      <literal>pcall()</literal> and <literal>xpcall()</literal> cannot catch certain errors, particularly timeout errors.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>tostring()</literal> does not include pointer addresses.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>string.match()</literal> has been patched to limit the recursion depth and to periodically check for a timeout.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>math.random()</literal> and <literal>math.randomseed()</literal> are replaced with versions that don't share state with PHP's <literal>rand()</literal>.
     </para>
    </listitem>
    <listitem>
     <para>
      The Lua 5.2 <literal>__pairs</literal> and <literal>__ipairs</literal> metamethods are supported by <literal>pairs()</literal> and <literal>ipairs()</literal>.
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </simplesect>

</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
