Skip to content

stream_copy_to_stream: document offset and socket timeout behavior #5860

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lacatoire merged 1 commit into from
Sep 24, 2026
+32 −9
Merged

stream_copy_to_stream: document offset and socket timeout behavior #5860

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 32 additions & 9 deletions reference/stream/functions/stream-copy-to-stream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down