reference/stream/functions/stream-select.xml
a123b24db5b3e42841179fea13cd508418fc45c7
a123b24db5b3e42841179fea13cd508418fc45c7
...
...
@@ -4,17 +4,17 @@
4
4
<refnamediv>
5
5
<refname>stream_select</refname>
6
6
<refpurpose>Runs the equivalent of the select() system call on the given
7
-
arrays of streams with a timeout specified by tv_sec and tv_usec </refpurpose>
7
+
arrays of streams with a timeout specified by seconds and microseconds</refpurpose>
8
8
</refnamediv>
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>int</type><methodname>stream_select</methodname>
13
-
<methodparam><type>array</type><parameter role="reference">read</parameter></methodparam>
14
-
<methodparam><type>array</type><parameter role="reference">write</parameter></methodparam>
15
-
<methodparam><type>array</type><parameter role="reference">except</parameter></methodparam>
16
-
<methodparam><type>int</type><parameter>tv_sec</parameter></methodparam>
17
-
<methodparam choice="opt"><type>int</type><parameter>tv_usec</parameter><initializer>0</initializer></methodparam>
12
+
<type class="union"><type>int</type><type>false</type></type><methodname>stream_select</methodname>
13
+
<methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">read</parameter></methodparam>
14
+
<methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">write</parameter></methodparam>
15
+
<methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">except</parameter></methodparam>
16
+
<methodparam><type class="union"><type>int</type><type>null</type></type><parameter>seconds</parameter></methodparam>
17
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>microseconds</parameter><initializer>&null;</initializer></methodparam>
18
18
</methodsynopsis>
19
19
<para>
20
20
The <function>stream_select</function> function accepts arrays of streams and
...
...
@@ -61,34 +61,28 @@
61
61
<parameter>read</parameter>, <parameter>write</parameter> and
62
62
<parameter>except</parameter> are modified to indicate which stream
63
63
resource(s) actually changed status.
64
+
The original keys of the &array;s are preserved.
64
65
</para>
65
66
</note>
66
-
<simpara>
67
-
You do not need to pass every array to
68
-
<function>stream_select</function>. You can leave it out and use an
69
-
empty array or &null; instead. Also do not forget that those arrays are
70
-
passed <emphasis>by reference</emphasis> and will be modified after
71
-
<function>stream_select</function> returns.
72
-
</simpara>
73
67
</listitem>
74
68
</varlistentry>
75
69
<varlistentry>
76
-
<term><parameter>tv_sec</parameter></term>
70
+
<term><parameter>seconds</parameter></term>
77
71
<listitem>
78
72
<para>
79
-
The <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter>
73
+
The <parameter>seconds</parameter> and <parameter>microseconds</parameter>
80
74
together form the <emphasis>timeout</emphasis> parameter,
81
-
<parameter>tv_sec</parameter> specifies the number of seconds while
82
-
<parameter>tv_usec</parameter> the number of microseconds.
75
+
<parameter>seconds</parameter> specifies the number of seconds while
76
+
<parameter>microseconds</parameter> the number of microseconds.
83
77
The <parameter>timeout</parameter> is an upper bound on the amount of time
84
78
that <function>stream_select</function> will wait before it returns.
85
-
If <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter> are
79
+
If <parameter>seconds</parameter> and <parameter>microseconds</parameter> are
86
80
both set to <literal>0</literal>, <function>stream_select</function> will
87
81
not wait for data - instead it will return immediately, indicating the
88
82
current status of the streams.
89
83
</para>
90
84
<para>
91
-
If <parameter>tv_sec</parameter> is &null; <function>stream_select</function>
85
+
If <parameter>seconds</parameter> is &null; <function>stream_select</function>
92
86
can block indefinitely, returning only when an event on one of the
93
87
watched streams occurs (or if a signal interrupts the system call).
94
88
</para>
...
...
@@ -114,10 +108,10 @@
114
108
</listitem>
115
109
</varlistentry>
116
110
<varlistentry>
117
-
<term><parameter>tv_usec</parameter></term>
111
+
<term><parameter>microseconds</parameter></term>
118
112
<listitem>
119
113
<para>
120
-
See <parameter>tv_sec</parameter> description.
114
+
See <parameter>seconds</parameter> description.
121
115
</para>
122
116
</listitem>
123
117
</varlistentry>
...
...
@@ -136,6 +130,28 @@
136
130
</para>
137
131
</refsect1>
138
132
133
+
<refsect1 role="changelog">
134
+
&reftitle.changelog;
135
+
<informaltable>
136
+
<tgroup cols="2">
137
+
<thead>
138
+
<row>
139
+
<entry>&Version;</entry>
140
+
<entry>&Description;</entry>
141
+
</row>
142
+
</thead>
143
+
<tbody>
144
+
<row>
145
+
<entry>8.1.0</entry>
146
+
<entry>
147
+
<parameter>microseconds</parameter> is now nullable.
148
+
</entry>
149
+
</row>
150
+
</tbody>
151
+
</tgroup>
152
+
</informaltable>
153
+
</refsect1>
154
+
139
155
<refsect1 role="examples">
140
156
&reftitle.examples;
141
157
<para>
...
...
@@ -217,16 +233,16 @@ if (false === stream_select($r, $w, $e, 0)) {
217
233
</para>
218
234
</note>
219
235
<note>
220
-
<para>
221
-
Windows compatibility: <function>stream_select</function> used on a
222
-
pipe returned from <function>proc_open</function> may cause data loss
223
-
under Windows 98.
224
-
</para>
236
+
<title>Windows compatibility</title>
225
237
<para>
226
238
Use of <function>stream_select</function> on
227
239
file descriptors returned by <function>proc_open</function> will fail
228
240
and return &false; under Windows.
229
241
</para>
242
+
<para>
243
+
<constant>STDIN</constant> from a console changes status as soon as <emphasis>any</emphasis>
244
+
input events are available, but reading from the stream may still block.
245
+
</para>
230
246
</note>
231
247
</refsect1>
232
248
...
...
@@ -237,7 +253,6 @@ if (false === stream_select($r, $w, $e, 0)) {
237
253
</simplelist>
238
254
</refsect1>
239
255
</refentry>
240
-
241
256
<!-- Keep this comment at the end of the file
242
257
Local variables:
243
258
mode: sgml
244
259