reference/filesystem/functions/fwrite.xml
bb6247b68128cab1b166b49a3a73a87f40333267
...
...
@@ -9,15 +9,15 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>int</type><methodname>fwrite</methodname>
13
-
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>string</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
12
+
<type class="union"><type>int</type><type>false</type></type><methodname>fwrite</methodname>
13
+
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>data</parameter></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<simpara>
18
18
<function>fwrite</function> writes the contents of
19
-
<parameter>string</parameter> to the file stream pointed to by
20
-
<parameter>handle</parameter>.
19
+
<parameter>data</parameter> to the file stream pointed to by
20
+
<parameter>stream</parameter>.
21
21
</simpara>
22
22
</refsect1>
23
23

...
...
@@ -26,13 +26,13 @@
26
26
<para>
27
27
<variablelist>
28
28
<varlistentry>
29
-
<term><parameter>handle</parameter></term>
29
+
<term><parameter>stream</parameter></term>
30
30
<listitem>
31
31
&fs.file.pointer;
32
32
</listitem>
33
33
</varlistentry>
34
34
<varlistentry>
35
-
<term><parameter>string</parameter></term>
35
+
<term><parameter>data</parameter></term>
36
36
<listitem>
37
37
<para>
38
38
The string that is to be written.
...
...
@@ -43,17 +43,9 @@
43
43
<term><parameter>length</parameter></term>
44
44
<listitem>
45
45
<para>
46
-
If the <parameter>length</parameter> argument is given, writing will
47
-
stop after <parameter>length</parameter> bytes have been written or
48
-
the end of <parameter>string</parameter> is reached, whichever comes
49
-
first.
50
-
</para>
51
-
<para>
52
-
Note that if the <parameter>length</parameter> argument is given,
53
-
then the <link
54
-
linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
55
-
configuration option will be ignored and no slashes will be
56
-
stripped from <parameter>string</parameter>.
46
+
If <parameter>length</parameter> is an &integer;, writing will stop
47
+
after <parameter>length</parameter> bytes have been written or the
48
+
end of <parameter>data</parameter> is reached, whichever comes first.
57
49
</para>
58
50
</listitem>
59
51
</varlistentry>
...
...
@@ -65,10 +57,81 @@
65
57
&reftitle.returnvalues;
66
58
<simpara>
67
59
<function>fwrite</function> returns the number of bytes
68
-
written, or &false; on error.
60
+
written, &return.falseforfailure;.
69
61
</simpara>
70
62
</refsect1>
71
63

64
+
<refsect1 role="errors">
65
+
&reftitle.errors;
66
+
<para>
67
+
<function>fwrite</function> raises <constant>E_WARNING</constant> on failure.
68
+
</para>
69
+
</refsect1>
70
+

71
+
<refsect1 role="changelog">
72
+
&reftitle.changelog;
73
+
<informaltable>
74
+
<tgroup cols="2">
75
+
<thead>
76
+
<row>
77
+
<entry>&Version;</entry>
78
+
<entry>&Description;</entry>
79
+
</row>
80
+
</thead>
81
+
<tbody>
82
+
<row>
83
+
<entry>8.0.0</entry>
84
+
<entry>
85
+
<parameter>length</parameter> is nullable now.
86
+
</entry>
87
+
</row>
88
+
</tbody>
89
+
</tgroup>
90
+
</informaltable>
91
+
</refsect1>
92
+

93
+
<refsect1 role="examples">
94
+
&reftitle.examples;
95
+
<para>
96
+
<example>
97
+
<title>A simple <function>fwrite</function> example</title>
98
+
<programlisting role="php">
99
+
<![CDATA[
100
+
<?php
101
+
$filename = 'test.txt';
102
+
$somecontent = "Add this to the file\n";
103
+

104
+
// Let's make sure the file exists and is writable first.
105
+
if (is_writable($filename)) {
106
+

107
+
// In our example we're opening $filename in append mode.
108
+
// The file pointer is at the bottom of the file hence
109
+
// that's where $somecontent will go when we fwrite() it.
110
+
if (!$fp = fopen($filename, 'a')) {
111
+
echo "Cannot open file ($filename)";
112
+
exit;
113
+
}
114
+

115
+
// Write $somecontent to our opened file.
116
+
if (fwrite($fp, $somecontent) === FALSE) {
117
+
echo "Cannot write to file ($filename)";
118
+
exit;
119
+
}
120
+

121
+
echo "Success, wrote ($somecontent) to file ($filename)";
122
+

123
+
fclose($fp);
124
+

125
+
} else {
126
+
echo "The file $filename is not writable";
127
+
}
128
+
?>
129
+
]]>
130
+
</programlisting>
131
+
</example>
132
+
</para>
133
+
</refsect1>
134
+

72
135
<refsect1 role="notes">
73
136
&reftitle.notes;
74
137
<note>
...
...
@@ -76,7 +139,7 @@
76
139
Writing to a network stream may end before the whole string is written.
77
140
Return value of <function>fwrite</function> may be checked:
78
141
<programlisting role="php">
79
-
<![CDATA[
142
+
<![CDATA[
80
143
<?php
81
144
function fwrite_stream($fp, $string) {
82
145
for ($written = 0; $written < strlen($string); $written += $fwrite) {
...
...
@@ -102,9 +165,9 @@ function fwrite_stream($fp, $string) {
102
165
</note>
103
166
<note>
104
167
<para>
105
-
If <parameter>handle</parameter> was <function>fopen</function>ed in
168
+
If <parameter>stream</parameter> was <function>fopen</function>ed in
106
169
append mode, <function>fwrite</function>s are atomic (unless the size of
107
-
<parameter>string</parameter> exceeds the filesystem's block size, on some
170
+
<parameter>data</parameter> exceeds the filesystem's block size, on some
108
171
platforms, and as long as the file is on a local filesystem). That is,
109
172
there is no need to <function>flock</function> a resource before calling
110
173
<function>fwrite</function>; all of the data will be written without
...
...
@@ -115,8 +178,8 @@ function fwrite_stream($fp, $string) {
115
178
<para>
116
179
If writing twice to the file pointer, then the data will be appended to
117
180
the end of the file content:
118
-
<programlisting role="php">
119
-
<![CDATA[
181
+
<programlisting role="php">
182
+
<![CDATA[
120
183
<?php
121
184
$fp = fopen('data.txt', 'w');
122
185
fwrite($fp, '1');
...
...
@@ -126,53 +189,11 @@ fclose($fp);
126
189
// the content of 'data.txt' is now 123 and not 23!
127
190
?>
128
191
]]>
129
-
</programlisting>
192
+
</programlisting>
130
193
</para>
131
194
</note>
132
195
</refsect1>
133
196

134
-
<refsect1 role="examples">
135
-
&reftitle.examples;
136
-
<para>
137
-
<example>
138
-
<title>A simple <function>fwrite</function> example</title>
139
-
<programlisting role="php">
140
-
<![CDATA[
141
-
<?php
142
-
$filename = 'test.txt';
143
-
$somecontent = "Add this to the file\n";
144
-

145
-
// Let's make sure the file exists and is writable first.
146
-
if (is_writable($filename)) {
147
-

148
-
// In our example we're opening $filename in append mode.
149
-
// The file pointer is at the bottom of the file hence
150
-
// that's where $somecontent will go when we fwrite() it.
151
-
if (!$handle = fopen($filename, 'a')) {
152
-
echo "Cannot open file ($filename)";
153
-
exit;
154
-
}
155
-

156
-
// Write $somecontent to our opened file.
157
-
if (fwrite($handle, $somecontent) === FALSE) {
158
-
echo "Cannot write to file ($filename)";
159
-
exit;
160
-
}
161
-

162
-
echo "Success, wrote ($somecontent) to file ($filename)";
163
-

164
-
fclose($handle);
165
-

166
-
} else {
167
-
echo "The file $filename is not writable";
168
-
}
169
-
?>
170
-
]]>
171
-
</programlisting>
172
-
</example>
173
-
</para>
174
-
</refsect1>
175
-

176
197
<refsect1 role="seealso">
177
198
&reftitle.seealso;
178
199
<para>
179
200