Document zend.max_allowed_stack_size and related parameters

Author: arnaud-lb

appendices/ini.list.xml

@@ -782,6 +782,12 @@
        <entry><constant>INI_SYSTEM</constant></entry>
        <entry>Available as of PHP 8.3.0</entry>
       </row>
+      <row>
+      <entry><link linkend="ini.fiber.stack-size">fiber.stack_size</link></entry>
+       <entry></entry>
+       <entry><constant>INI_ALL</constant></entry>
+       <entry>Available as of PHP 8.1.0</entry>
+      </row>
       <row>
        <entry><link linkend="ini.zend.multibyte">zend.multibyte</link></entry>
        <entry><literal>"0"</literal></entry>

appendices/migration82/other-changes.xml

@@ -257,12 +257,11 @@
    For backwards compatibility, interpretation of these values has not changed.
    This affects the following settings:
 
-   <!-- TODO: Add missing INI links after directives have been documented -->
    <simplelist>
     <member><link linkend="ini.bcmath.scale">bcmath.scale</link></member>
     <member><link linkend="ini.com.code-page">com.code_page</link></member>
     <member><link linkend="ini.default-socket-timeout">default_socket_timeout</link></member>
-    <member>fiber.stack_size</member>
+    <member><link linkend="ini.fiber.stack-size">fiber.stack_size</link></member>
     <member><link linkend="ini.hard-timeout">hard_timeout</link></member>
     <member><link linkend="ini.intl.error-level">intl.error_level</link></member>
     <member><link linkend="ini.ldap.max_links">ldap.max_links</link></member>

appendices/migration83/other-changes.xml

@@ -505,7 +505,7 @@
    </listitem>
    <listitem>
     <para>
-     <!--<link linkend="ini.zend.max_allowed_stack_size">-->zend.max_allowed_stack_size<!--</link>-->
+     <link linkend="ini.zend.max-allowed-stack-size">zend.max_allowed_stack_size</link>
     is a new INI directive to set the maximum allowed stack size.
     Possible values are <literal>0</literal> (detect the process or thread maximum stack size),
     <literal>-1</literal> (no limit), or a positive number of bytes.
@@ -514,10 +514,10 @@
     size, a known system default is used.
     Setting this value too high has the same effect as disabling the stack size limit.
     Fibers use
-    <!-- link TODO -->fiber.stack_size<!-- /link -->
+    <link linkend="ini.fiber.stack-size">fiber.stack_size</link>
     as maximum allowed stack size.
     An <classname>Error</classname> is thrown when the process call stack exceeds
-    <!-- link TODO -->zend.max_allowed_stack_size-zend.reserved_stack_size<!-- /link-->
+    <link linkend="ini.zend.max-allowed-stack-size">zend.max_allowed_stack_size</link>-<link linkend="ini.zend.reserved-stack-size">zend.reserved_stack_size</link>
     bytes, to prevent stack-overflow-induced segmentation faults, with
     the goal of making debugging easier.
     The stack size increases during uncontrolled recursions involving internal functions
@@ -531,7 +531,7 @@
    </listitem>
    <listitem>
     <para>
-     <!--<link linkend="ini.zend.reserved_stack_size">-->zend.reserved_stack_size<!--</link>-->
+     <link linkend="ini.zend.reserved-stack-size">zend.reserved_stack_size</link>
      is a new INI directive to set the reserved stack size, in bytes.
      This is subtracted from the max allowed stack size,
      as a buffer, when checking the stack size.

reference/info/ini.xml

@@ -99,6 +99,24 @@
      <entry><constant>INI_ALL</constant></entry>
      <entry></entry>
     </row>
+    <row>
+     <entry><link linkend="ini.zend.max-allowed-stack-size">zend.max_allowed_stack_size</link></entry>
+     <entry>"0"</entry>
+     <entry><constant>INI_SYSTEM</constant></entry>
+     <entry>Available as of PHP 8.3.0.</entry>
+    </row>
+    <row>
+     <entry><link linkend="ini.zend.reserved-stack-size">zend.reserved_stack_size</link></entry>
+     <entry>"0"</entry>
+     <entry><constant>INI_SYSTEM</constant></entry>
+     <entry>Available as of PHP 8.3.0.</entry>
+    </row>
+    <row>
+     <entry><link linkend="ini.fiber.stack-size">fiber.stack_size</link></entry>
+     <entry></entry>
+     <entry><constant>INI_ALL</constant></entry>
+     <entry>Available as of PHP 8.1.0.</entry>
+    </row>
     </tbody>
    </tgroup>
   </table>
@@ -304,6 +322,110 @@
     </listitem>
    </varlistentry>
 
+   <varlistentry xml:id="ini.zend.max-allowed-stack-size">
+    <term>
+     <parameter>zend.max_allowed_stack_size</parameter>
+     <type>int</type>
+    </term>
+    <listitem>
+     <para>
+      The maximum native stack space that the operating system allows the
+      program to consume.
+      Trying to consume more than the operating system allows
+      typically results in a hard crash with no easily available debugging
+      information.
+      To make debugging easier, the engine throws an
+      <classname>Error</classname>
+      before it happens (when the program uses more than
+      <link linkend="ini.zend.max-allowed-stack-size">zend.max_allowed_stack_size</link>-<link linkend="ini.zend.reserved-stack-size">zend.reserved_stack_size</link>
+      bytes of stack).
+     </para>
+     <para>
+      Recursion in user-defined code does not consume native stack space.
+      However, internal functions and magic methods do.
+      Very deep recursion involving these functions can cause the program to
+      exhaust all available native stack space.
+     </para>
+     <para>
+      Possible values for this parameter are:
+      <simplelist>
+       <member>
+        <literal>0</literal>:
+        Auto-detect the maximum native stack space that the operating system
+        allows the program to consume.
+        This is the default.
+        When detection is not possible, a known system default is used.
+       </member>
+       <member>
+        <literal>-1</literal>: Disables stack size checking in the engine.
+       </member>
+       <member>
+        Positive integer: A fixed size, in bytes.
+        Setting this value too high has the same effect as disabling stack size
+        checking.
+       </member>
+      </simplelist>
+     </para>
+     <para>
+      As the stack size of
+      <link linkend="language.fibers">fibers</link>
+      is determined by
+      <link linkend="ini.fiber.stack-size">fiber.stack_size</link>,
+      the value of this parameter is used instead of
+      <link linkend="ini.zend.max-allowed-stack-size">zend.max_allowed_stack_size</link>
+      when checking stack usage during the execution of a Fiber.
+     </para>
+     <note>
+      <para>
+       This is not related to stack <emphasis>buffer</emphasis> overflows, and is not a security
+       feature.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry xml:id="ini.zend.reserved-stack-size">
+    <term>
+     <parameter>zend.reserved_stack_size</parameter>
+     <type>int</type>
+    </term>
+    <listitem>
+     <para>
+      The reserved stack size, in bytes.
+      This is subtracted from the
+      <link linkend="ini.zend.max-allowed-stack-size">max allowed stack size</link>,
+      as a buffer, when checking the stack size.
+     </para>
+     <para>
+      Possible values for this parameter are:
+      <simplelist>
+       <member>
+        <literal>0</literal>: Auto-detect a sensible size.
+       </member>
+       <member>
+        Positive integer: A fixed size, in bytes.
+       </member>
+      </simplelist>
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry xml:id="ini.fiber.stack-size">
+    <term>
+     <parameter>fiber.stack_size</parameter>
+     <type>int</type>
+    </term>
+    <listitem>
+     <para>
+      The native stack size, in bytes, allocated for each
+      <link linkend="language.fibers">Fiber</link>.
+     </para>
+     <para>
+      The default value is 1MiB on systems with a pointer size lower than
+      8 bytes, or 2MiB otherwise.
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
  </para>
 </section>