reference/filesystem/functions/fopen.xml
ea62fb83196997032641b50fe44420305466195e
ea62fb83196997032641b50fe44420305466195e
...
...
@@ -9,11 +9,11 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>resource</type><methodname>fopen</methodname>
12
+
<type class="union"><type>resource</type><type>false</type></type><methodname>fopen</methodname>
13
13
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
14
14
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
15
-
<methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>false</initializer></methodparam>
16
-
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
15
+
<methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>&false;</initializer></methodparam>
16
+
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
19
<function>fopen</function> binds a named resource, specified by
...
...
@@ -41,8 +41,8 @@
41
41
a local file, then it will try to open a stream on that file.
42
42
The file must be accessible to PHP, so you need to ensure that
43
43
the file access permissions allow this access.
44
-
If you have enabled &safemode;,
45
-
or <link linkend="ini.open-basedir">open_basedir</link> further
44
+
If you have enabled
45
+
<link linkend="ini.open-basedir">open_basedir</link> further
46
46
restrictions may apply.
47
47
</para>
48
48
<para>
...
...
@@ -123,9 +123,8 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
123
123
<row>
124
124
<entry><literal>'w+'</literal></entry>
125
125
<entry>
126
-
Open for reading and writing; place the file pointer at
127
-
the beginning of the file and truncate the file to zero
128
-
length. If the file does not exist, attempt to create it.
126
+
Open for reading and writing; otherwise it has the
127
+
same behavior as <literal>'w'</literal>.
129
128
</entry>
130
129
</row>
131
130
<row>
...
...
@@ -133,6 +132,7 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
133
132
<entry>
134
133
Open for writing only; place the file pointer at the end of
135
134
the file. If the file does not exist, attempt to create it.
135
+
In this mode, <function>fseek</function> has no effect, writes are always appended.
136
136
</entry>
137
137
</row>
138
138
<row>
...
...
@@ -140,7 +140,8 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
140
140
<entry>
141
141
Open for reading and writing; place the file pointer at
142
142
the end of the file. If the file does not exist, attempt to
143
-
create it.
143
+
create it. In this mode, <function>fseek</function> only affects
144
+
the reading position, writes are always appended.
144
145
</entry>
145
146
</row>
146
147
<row>
...
...
@@ -185,6 +186,13 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
185
186
behavior as <literal>'c'</literal>.
186
187
</entry>
187
188
</row>
189
+
<row>
190
+
<entry><literal>'e'</literal></entry>
191
+
<entry>
192
+
Set close-on-exec flag on the opened file descriptor. Only
193
+
available in PHP compiled on POSIX.1-2008 conform systems.
194
+
</entry>
195
+
</row>
188
196
</tbody>
189
197
</tgroup>
190
198
</table>
...
...
@@ -196,7 +204,7 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
196
204
break, you need to use the correct line-ending character(s) for your
197
205
operating system. Unix based systems use <literal>\n</literal> as the
198
206
line ending character, Windows based systems use <literal>\r\n</literal>
199
-
as the line ending characters and Macintosh based systems use
207
+
as the line ending characters and Macintosh based systems (Mac OS Classic) used
200
208
<literal>\r</literal> as the line ending character.
201
209
</para>
202
210
<para>
...
...
@@ -214,34 +222,35 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
214
222
of the <parameter>mode</parameter> parameter.
215
223
</para>
216
224
<para>
217
-
The default translation mode depends on the SAPI and version of PHP that
218
-
you are using, so you are encouraged to always specify the appropriate
219
-
flag for portability reasons. You should use the <literal>'t'</literal>
225
+
The default translation mode is <literal>'b'</literal>.
226
+
You can use the <literal>'t'</literal>
220
227
mode if you are working with plain-text files and you use
221
228
<literal>\n</literal> to delimit your line endings in your script, but
222
-
expect your files to be readable with applications such as notepad. You
229
+
expect your files to be readable with applications such as old versions of notepad. You
223
230
should use the <literal>'b'</literal> in all other cases.
224
231
</para>
225
232
<para>
226
-
If you do not specify the 'b' flag when working with binary files, you
233
+
If you specify the 't' flag when working with binary files, you
227
234
may experience strange problems with your data, including broken image
228
235
files and strange problems with <literal>\r\n</literal> characters.
229
236
</para>
230
237
</note>
231
238
<note>
232
239
<para>
233
-
For portability, it is strongly recommended that you always
234
-
use the 'b' flag when opening files with <function>fopen</function>.
235
-
</para>
236
-
</note>
237
-
<note>
238
-
<para>
239
-
Again, for portability, it is also strongly recommended that
240
+
For portability, it is also strongly recommended that
240
241
you re-write code that uses or relies upon the <literal>'t'</literal>
241
242
mode so that it uses the correct line endings and
242
243
<literal>'b'</literal> mode instead.
243
244
</para>
244
245
</note>
246
+
<note>
247
+
<simpara>
248
+
The <parameter>mode</parameter> is ignored for <filename>php://output</filename>,
249
+
<filename>php://input</filename>, <filename>php://stdin</filename>,
250
+
<filename>php://stdout</filename>, <filename>php://stderr</filename> and
251
+
<filename>php://fd</filename> stream wrappers.
252
+
</simpara>
253
+
</note>
245
254
</listitem>
246
255
</varlistentry>
247
256
<varlistentry>
...
...
@@ -267,18 +276,14 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
267
276
<refsect1 role="returnvalues">
268
277
&reftitle.returnvalues;
269
278
<para>
270
-
Returns a file pointer resource on success, or &false; on error.
279
+
Returns a file pointer resource on success,
280
+
&return.falseforfailure;
271
281
</para>
272
282
</refsect1>
273
283
274
284
<refsect1 role="errors">
275
285
&reftitle.errors;
276
-
<para>
277
-
If the open fails, an error of level
278
-
<constant>E_WARNING</constant> is generated. You may use <link
279
-
linkend="language.operators.errorcontrol">@</link> to suppress this
280
-
warning.
281
-
</para>
286
+
&fs.emits.warning.on.failure;
282
287
</refsect1>
283
288
284
289
<refsect1 role="changelog">
...
...
@@ -294,27 +299,9 @@ $handle = fopen("c:\\folder\\resource.txt", "r");
294
299
</thead>
295
300
<tbody>
296
301
<row>
297
-
<entry>5.2.6</entry>
298
-
<entry>
299
-
The <literal>'c'</literal> and <literal>'c+'</literal> options were
300
-
added
301
-
</entry>
302
-
</row>
303
-
<row>
304
-
<entry>4.3.2</entry>
305
-
<entry>
306
-
As of PHP 4.3.2, the default mode is set to binary for all platforms
307
-
that distinguish between binary and text mode. If you are having
308
-
problems with your scripts after upgrading, try using the
309
-
<literal>'t'</literal> flag as a workaround until you have made your
310
-
script more portable as mentioned before
311
-
</entry>
312
-
</row>
313
-
<row>
314
-
<entry>4.3.2</entry>
302
+
<entry>7.0.16, 7.1.2</entry>
315
303
<entry>
316
-
The <literal>'x'</literal> and <literal>'x+'</literal> options were
317
-
added
304
+
The <literal>'e'</literal> option was added.
318
305
</entry>
319
306
</row>
320
307
</tbody>
...
...
@@ -345,7 +332,6 @@ $handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
345
332
<refsect1 role="notes">
346
333
&reftitle.notes;
347
334
&warn.ssl-non-standard;
348
-
¬e.sm.uidcheck.dir;
349
335
<note>
350
336
<para>
351
337
If you are experiencing problems with reading and writing to files and
352
338