[doc-en] master: stream_copy_to_stream: document offset and socket timeout behavior (#5860)

Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-24T11:21:32+02:00 Commit: https://github.com/php/doc-en/commit/a88dc819007e9f520c8f912aab9c72aca6485d41 Raw diff: https://github.com/php/doc-en/commit/a88dc819007e9f520c8f912aab9c72aca6485d41.diff stream_copy_to_stream: document offset and socket timeout behavior (#5860) A zero or negative offset keeps the current position, a positive one seeks from the start of the stream. Copying from a blocking socket stops when the stream timeout is reached, and false may be returned even though data has already been written to the destination. Changed paths: M reference/stream/functions/stream-copy-to-stream.xml Diff: diff --git a/reference/stream/functions/stream-copy-to-stream.xml b/reference/stream/functions/stream-copy-to-stream.xml index 2e26b6e79ca7..b426fc175447 100644 --- a/reference/stream/functions/stream-copy-to-stream.xml +++ b/reference/stream/functions/stream-copy-to-stream.xml @@ -14,14 +14,14 @@ <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam> <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam> </methodsynopsis> - <para> + <simpara> Makes a copy of up to <parameter>length</parameter> bytes - of data from the current position (or from the - <parameter>offset</parameter> position, if specified) in - <parameter>from</parameter> to <parameter>to</parameter>. If - <parameter>length</parameter> is &null;, all remaining content in + of data from <parameter>from</parameter> to <parameter>to</parameter>, + starting at the current position in <parameter>from</parameter>, or at + <parameter>offset</parameter> if it is greater than <literal>0</literal>. + If <parameter>length</parameter> is &null;, all remaining content in <parameter>from</parameter> will be copied. - </para> + </simpara> </refsect1> <refsect1 role="parameters"> @@ -55,9 +55,16 @@ <varlistentry> <term><parameter>offset</parameter></term> <listitem> - <para> - The offset where to start to copy data - </para> + <simpara> + If greater than <literal>0</literal>, the position in + <parameter>from</parameter>, counted from the start of the stream, + at which to start copying: <parameter>from</parameter> is first moved + to that position, as with <function>fseek</function> and + <constant>SEEK_SET</constant>. + If <literal>0</literal> (the default) or negative, no seek is + performed and copying starts at the current position in + <parameter>from</parameter>. + </simpara> </listitem> </varlistentry> </variablelist> @@ -115,6 +122,22 @@ echo stream_copy_to_stream($src, $dest2) . " bytes copied to remainder.txt\n"; </para> </refsect1> + <refsect1 role="notes"> + &reftitle.notes; + <note> + <simpara> + When <parameter>from</parameter> is a socket stream in blocking mode, + copying stops as soon as no data is received within the stream timeout, + even if the end of the stream has not been reached. + &false; may then be returned, even though the data read until then has + already been written to <parameter>to</parameter>. + This timeout defaults to + <link linkend="ini.default-socket-timeout">default_socket_timeout</link> + and can be changed with <function>stream_set_timeout</function>. + </simpara> + </note> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <para>