reference/filesystem/functions/stat.xml
f80105b4fc1196bd8d5fecb98d686b580b1ff65d
...
...
@@ -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.stat">
3
+
<refentry xml:id="function.stat" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>stat</refname>
6
6
<refpurpose>Gives information about a file</refpurpose>
...
...
@@ -9,13 +9,16 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>array</type><methodname>stat</methodname>
12
+
<type class="union"><type>array</type><type>false</type></type><methodname>stat</methodname>
13
13
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
14
14
</methodsynopsis>
15
15
<para>
16
16
Gathers the statistics of the file named by
17
17
<parameter>filename</parameter>. If <parameter>filename</parameter> is a
18
18
symbolic link, statistics are from the file itself, not the symlink.
19
+
Prior to PHP 7.4.0, on Windows <abbrev>NTS</abbrev> builds the <literal>size</literal>,
20
+
<literal>atime</literal>, <literal>mtime</literal> and <literal>ctime</literal>
21
+
statistics have been from the symlink, in this case.
19
22
</para>
20
23
<para>
21
24
<function>lstat</function> is identical to <function>stat</function>
...
...
@@ -57,17 +60,17 @@
57
60
<row>
58
61
<entry>0</entry>
59
62
<entry>dev</entry>
60
-
<entry>device number</entry>
63
+
<entry>device number ***</entry>
61
64
</row>
62
65
<row>
63
66
<entry>1</entry>
64
67
<entry>ino</entry>
65
-
<entry>inode number *</entry>
68
+
<entry>inode number ****</entry>
66
69
</row>
67
70
<row>
68
71
<entry>2</entry>
69
72
<entry>mode</entry>
70
-
<entry>inode protection mode</entry>
73
+
<entry>inode protection mode *****</entry>
71
74
</row>
72
75
<row>
73
76
<entry>3</entry>
...
...
@@ -122,11 +125,79 @@
122
125
</tbody>
123
126
</tgroup>
124
127
</table>
125
-
* On Windows this will always be 0.
128
+
</para>
129
+
<para>
130
+
* On Windows this will always be <literal>0</literal>.
126
131
</para>
127
132
<para>
128
133
** Only valid on systems supporting the st_blksize type - other
129
-
systems (e.g. Windows) return -1.
134
+
systems (e.g. Windows) return <literal>-1</literal>.
135
+
</para>
136
+
<para>
137
+
*** On Windows, as of PHP 7.4.0, this is the serial number of the volume that contains the file,
138
+
which is a 64-bit <emphasis>unsigned</emphasis> integer, so may overflow.
139
+
Previously, it was the numeric representation of the drive letter (e.g. <literal>2</literal>
140
+
for <literal>C:</literal>) for <function>stat</function>, and <literal>0</literal> for
141
+
<function>lstat</function>.
142
+
</para>
143
+
<para>
144
+
**** On Windows, as of PHP 7.4.0, this is the identifier associated with the file,
145
+
which is a 64-bit <emphasis>unsigned</emphasis> integer, so may overflow.
146
+
Previously, it was always <literal>0</literal>.
147
+
</para>
148
+
<para>
149
+
***** On Windows, the writable permission bit is set according to the read-only
150
+
file attribute, and the same value is reported for all users, group and owner.
151
+
The ACL is not taken into account, contrary to <function>is_writable</function>.
152
+
</para>
153
+
<para>
154
+
The value of <literal>mode</literal> contains information read by several functions.
155
+
When written in octal, starting from the right, the first three digits are returned by
156
+
<function>chmod</function>. The next digit is ignored by PHP. The next two digits indicate
157
+
the file type:
158
+
<table>
159
+
<title><literal>mode</literal> file types</title>
160
+
<tgroup cols="2">
161
+
<thead>
162
+
<row>
163
+
<entry><literal>mode</literal> in octal</entry>
164
+
<entry>Meaning</entry>
165
+
</row>
166
+
</thead>
167
+
<tbody>
168
+
<row>
169
+
<entry><literal>0140000</literal></entry>
170
+
<entry>socket</entry>
171
+
</row>
172
+
<row>
173
+
<entry><literal>0120000</literal></entry>
174
+
<entry>link</entry>
175
+
</row>
176
+
<row>
177
+
<entry><literal>0100000</literal></entry>
178
+
<entry>regular file</entry>
179
+
</row>
180
+
<row>
181
+
<entry><literal>0060000</literal></entry>
182
+
<entry>block device</entry>
183
+
</row>
184
+
<row>
185
+
<entry><literal>0040000</literal></entry>
186
+
<entry>directory</entry>
187
+
</row>
188
+
<row>
189
+
<entry><literal>0020000</literal></entry>
190
+
<entry>character device</entry>
191
+
</row>
192
+
<row>
193
+
<entry><literal>0010000</literal></entry>
194
+
<entry>fifo</entry>
195
+
</row>
196
+
</tbody>
197
+
</tgroup>
198
+
</table>
199
+
So for example a regular file could be <literal>0100644</literal> and a directory could be
200
+
<literal>0040755</literal>.
130
201
</para>
131
202
<para>
132
203
In case of error, <function>stat</function> returns &false;.
...
...
@@ -141,6 +212,37 @@
141
212
</para>
142
213
</refsect1>
143
214

215
+
<refsect1 role="changelog">
216
+
&reftitle.changelog;
217
+
<informaltable>
218
+
<tgroup cols="2">
219
+
<thead>
220
+
<row>
221
+
<entry>&Version;</entry>
222
+
<entry>&Description;</entry>
223
+
</row>
224
+
</thead>
225
+
<tbody>
226
+
<row>
227
+
<entry>7.4.0</entry>
228
+
<entry>
229
+
On Windows, the device number is now the serial number of the volume that
230
+
contains the file, and the inode number is the identifier associated with the file.
231
+
</entry>
232
+
</row>
233
+
<row>
234
+
<entry>7.4.0</entry>
235
+
<entry>
236
+
The <literal>size</literal>, <literal>atime</literal>, <literal>mtime</literal> and
237
+
<literal>ctime</literal> statistics of symlinks are always those of the target.
238
+
This was previously not the case for <abbrev>NTS</abbrev> builds on Windows.
239
+
</entry>
240
+
</row>
241
+
</tbody>
242
+
</tgroup>
243
+
</informaltable>
244
+
</refsect1>
245
+

144
246
<refsect1 role="examples">
145
247
&reftitle.examples;
146
248
<para>
...
...
@@ -219,12 +321,12 @@ if (!$stat) {
219
321
<member><function>fstat</function></member>
220
322
<member><function>filemtime</function></member>
221
323
<member><function>filegroup</function></member>
324
+
<member><classname>SplFileInfo</classname></member>
222
325
</simplelist>
223
326
</para>
224
327
</refsect1>
225
328

226
329
</refentry>
227
-

228
330
<!-- Keep this comment at the end of the file
229
331
Local variables:
230
332
mode: sgml
231
333