reference/filesystem/functions/flock.xml
0bfb0eb957e0468912af86bba09fae588010c1df
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.flock">
3
+
<refentry xml:id="function.flock" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>flock</refname>
6
6
<refpurpose>Portable advisory file locking</refpurpose>
...
...
@@ -10,9 +10,9 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>bool</type><methodname>flock</methodname>
13
-
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
13
+
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
14
14
<methodparam><type>int</type><parameter>operation</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter role="reference">wouldblock</parameter></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter role="reference">would_block</parameter><initializer>&null;</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
18
<function>flock</function> allows you to perform a simple reader/writer
...
...
@@ -20,16 +20,14 @@
20
20
derivatives and even Windows).
21
21
</para>
22
22
<para>
23
-
On versions of PHP before 5.3.2, the lock is released also by
24
-
<function>fclose</function> (which is also called automatically when script
25
-
finished).
23
+
The lock is released also by <function>fclose</function>,
24
+
or when <parameter>stream</parameter> is garbage collected.
26
25
</para>
27
26
<para>
28
27
PHP supports a portable way of locking complete files in an advisory way
29
28
(which means all accessing programs have to use the same way of locking
30
29
or it will not work). By default, this function will block until the
31
-
requested lock is acquired; this may be controlled (on non-Windows
32
-
platforms) with the <constant>LOCK_NB</constant> option documented below.
30
+
requested lock is acquired; this may be controlled with the <constant>LOCK_NB</constant> option documented below.
33
31
</para>
34
32
</refsect1>
35
33
...
...
@@ -38,7 +36,7 @@
38
36
<para>
39
37
<variablelist>
40
38
<varlistentry>
41
-
<term><parameter>handle</parameter></term>
39
+
<term><parameter>stream</parameter></term>
42
40
<listitem>
43
41
&fs.file.pointer;
44
42
</listitem>
...
...
@@ -68,17 +66,17 @@
68
66
</para>
69
67
<para>
70
68
It is also possible to add <constant>LOCK_NB</constant> as a bitmask to one
71
-
of the above operations if you don't want <function>flock</function> to
72
-
block while locking. (not supported on Windows)
69
+
of the above operations, if <function>flock</function> should not
70
+
block during the locking attempt.
73
71
</para>
74
72
</listitem>
75
73
</varlistentry>
76
74
<varlistentry>
77
-
<term><parameter>wouldblock</parameter></term>
75
+
<term><parameter>would_block</parameter></term>
78
76
<listitem>
79
77
<para>
80
-
The optional third argument is set to &true; if the lock would block
81
-
(EWOULDBLOCK errno condition). (not supported on Windows)
78
+
The optional third argument is set to 1 if the lock would block
79
+
(EWOULDBLOCK errno condition).
82
80
</para>
83
81
</listitem>
84
82
</varlistentry>
...
...
@@ -93,40 +91,6 @@
93
91
</para>
94
92
</refsect1>
95
93

96
-
<refsect1 role="changelog">
97
-
&reftitle.changelog;
98
-
<para>
99
-
<informaltable>
100
-
<tgroup cols="2">
101
-
<thead>
102
-
<row>
103
-
<entry>&Version;</entry>
104
-
<entry>&Description;</entry>
105
-
</row>
106
-
</thead>
107
-
<tbody>
108
-
<row>
109
-
<entry>5.3.2</entry>
110
-
<entry>
111
-
The automatic unlocking when the file's resource handle is closed was
112
-
removed. Unlocking now always has to be done manually.
113
-
</entry>
114
-
</row>
115
-
<row>
116
-
<entry>4.0.1</entry>
117
-
<entry>
118
-
The <literal>LOCK_XXX</literal> constants were added. Prior to that
119
-
you must use 1 for <constant>LOCK_SH</constant>, 2 for
120
-
<constant>LOCK_EX</constant>, 3 for <constant>LOCK_UN</constant> and
121
-
4 for <constant>LOCK_NB</constant>
122
-
</entry>
123
-
</row>
124
-
</tbody>
125
-
</tgroup>
126
-
</informaltable>
127
-
</para>
128
-
</refsect1>
129
-
130
94
<refsect1 role="examples">
131
95
&reftitle.examples;
132
96
<para>
...
...
@@ -207,14 +171,14 @@ fclose($fp);
207
171
</note>
208
172
<warning>
209
173
<para>
210
-
Assigning another value to <parameter>handle</parameter> argument in
174
+
Assigning another value to <parameter>stream</parameter> argument in
211
175
subsequent code will release the lock.
212
176
</para>
213
177
</warning>
214
178
<warning>
215
179
<para>
216
180
On some operating systems <function>flock</function> is implemented at
217
-
the process level. When using a multithreaded server API like ISAPI you
181
+
the process level. When using a multithreaded server API you
218
182
may not be able to rely on <function>flock</function> to protect files
219
183
against other PHP scripts running in parallel threads of the same server
220
184
instance!
...
...
@@ -222,14 +186,18 @@ fclose($fp);
222
186
<para>
223
187
<function>flock</function> is not supported on antiquated filesystems like
224
188
<literal>FAT</literal> and its derivates and will therefore always
225
-
return &false; under this environments (this is especially true for
226
-
Windows 98 users).
189
+
return &false; under these environments.
227
190
</para>
228
191
</warning>
192
+
<note>
193
+
<para>
194
+
On Windows, if the locking process opens the file a second time, it cannot
195
+
access the file through this second handle until it unlocks the file.
196
+
</para>
197
+
</note>
229
198
</refsect1>
230
199
231
200
</refentry>
232
-

233
201
<!-- Keep this comment at the end of the file
234
202
Local variables:
235
203
mode: sgml
236
204



Tools (Chinese (Simplified) Manual)