Skip to content

Commit

Permalink
Document zend.max_allowed_stack_size and related parameters
Browse files Browse the repository at this point in the history
  • Loading branch information
@arnaud-lb @Girgias
arnaud-lb authored and Girgias committed Jan 27, 2025
1 parent 4f6b571 commit b1116af
Show file tree
Hide file tree
Showing 4 changed files with 133 additions and 6 deletions.
6 changes: 6 additions & 0 deletions appendices/ini.list.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
3 changes: 1 addition & 2 deletions appendices/migration82/other-changes.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
8 changes: 4 additions & 4 deletions appendices/migration83/other-changes.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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.
Expand Down
122 changes: 122 additions & 0 deletions reference/info/ini.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down

0 comments on commit b1116af

Please sign in to comment.