❮ PHP Filesystem Reference
Example
Get information about a file:
Run Example »
Definition and Usage
The stat[] function returns information about a file.
Note: The results from this function will differ from server to server. The array may contain the number index, the name index, or both.
Note: The result of this function is cached. Use clearstatcache[] to clear the cache.
Syntax
Parameter Values
filename | Required. Specifies the path to the file |
Technical Details
An array with the following elements:
It returns an E_WARNING on failure |
4.0+ |
❮ PHP Filesystem Reference
[PHP 4, PHP 5, PHP 7, PHP 8]
stat — Gives information about a file
Description
stat[string $filename
]: array|false
lstat[] is identical to stat[] except it would instead be based off the symlinks status.
Parameters
filename
Path to the file.
Return Values
stat[] and fstat[] result format0 | dev | device number *** |
1 | ino | inode number **** |
2 | mode | inode protection mode ***** |
3 | nlink | number of links |
4 | uid | userid of owner * |
5 | gid | groupid of owner * |
6 | rdev | device type, if inode device |
7 | size | size in bytes |
8 | atime | time of last access [Unix timestamp] |
9 | mtime | time of last modification [Unix timestamp] |
10 | ctime | time of last inode change [Unix timestamp] |
11 | blksize | blocksize of filesystem IO ** |
12 | blocks | number of 512-byte blocks allocated ** |
* On Windows this will always be 0
.
** Only valid on systems supporting the st_blksize type - other systems [e.g. Windows] return -1
.
*** On Windows, as of PHP 7.4.0, this is the serial number of the volume that contains the file, which is a 64-bit unsigned integer, so may overflow. Previously, it was the numeric representation of the drive letter [e.g. 2
for C:
] for stat[], and
0
for lstat[].
**** On Windows, as of PHP 7.4.0, this is the identifier associated with the file, which is a 64-bit unsigned integer, so may overflow. Previously, it was always 0
.
***** On Windows, the writable permission bit is set according to the read-only file attribute, and the same value is reported for all users, group and owner. The ACL is not taken into account, contrary to is_writable[].
The value of mode
contains information read by several functions. When written in octal, starting from the right, the first three digits are returned by chmod[]. The next digit is ignored by PHP. The next two digits indicate the file type:
mode
file types0140000
| socket |
0120000
| link |
0100000
| regular file |
0060000
| block device |
0040000
| directory |
0020000
| character device |
0010000
| fifo |
So for example a regular file could be 0100644
and a directory could be 0040755
.
In case of error, stat[] returns false
.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Errors/Exceptions
Upon failure, an E_WARNING
is emitted.
Changelog
7.4.0 | On Windows, the device number is now the serial number of the volume that contains the file, and the inode number is the identifier associated with the file. |
7.4.0 | The size , atime , mtime and ctime statistics of symlinks are always those of the target. This was previously not the case for NTS builds on Windows.
|
Examples
Example #1 stat[] example
Example #2 Using stat[] information together with touch[]
Notes
Note:
Note that time resolution may differ from one file system to another.
Note: The results of this function are cached. See clearstatcache[] for more details.
Tip
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat[] family of functionality.
See Also
- lstat[] - Gives information about a file or symbolic link
- fstat[] - Gets information about a file using an open file pointer
- filemtime[] - Gets file modification time
- filegroup[] - Gets file group
- SplFileInfo
webmaster at askapache dot com ¶
8 years ago
On GNU/Linux you can retrieve the number of currently running processes on the machine by doing a stat for hard links on the '/proc' directory like so:
$ stat -c '%h' /proc
118
You can do the same thing in php by doing a stat on /proc and grabbing the [3] 'nlink' - number of links in the returned array.
Here is the function I'm using, it does a clearstatcache[] when called more than once.
int[118] Which is the number of processes that were running.
Example #1 get_process_count[] example
The above example will output:
webmaster at askapache dot com ¶
13 years ago
This is a souped up 'stat' function based on
many user-submitted code snippets and
@ //www.askapache.com/security/chmod-stat.html
Give it a filename, and it returns an array like stat.
|=---------[ Example Output ]
Array[
[perms] => Array
[
[umask] => 0022
[human] => -rw-r--r--
[octal1] => 644
[octal2] => 0644
[decimal] => 100644
[fileperms] => 33188
[mode1] => 33188
[mode2] => 33188
]
[filetype] => Array
[
[type] => file
[type_octal] => 0100000
[is_file] => 1
[is_dir] =>
[is_link] =>
[is_readable] => 1
[is_writable] => 1
]
[owner] => Array
[
[fileowner] => 035483
[filegroup] => 23472
[owner_name] => askapache
[group_name] => grp22558
]
[file] => Array
[
[filename] => /home/askapache/askapache-stat/htdocs/ok/g.php
[realpath] =>
[dirname] => /home/askapache/askapache-stat/htdocs/ok
[basename] => g.php
]
[device] => Array
[
[device] => 25
[device_number] => 0
[inode] => 92455020
[link_count] => 1
[link_to] =>
]
[size] => Array
[
[size] => 2652
[blocks] => 8
[block_size] => 8192
]
[time] => Array
[
[mtime] => 1227685253
[atime] => 1227685138
[ctime] => 1227685253
[accessed] => 2008 Nov Tue 23:38:58
[modified] => 2008 Nov Tue 23:40:53
[created] => 2008 Nov Tue 23:40:53
]
]
admin at smitelli dot com ¶
16 years ago
There's an important [yet little-known] problem with file dates on Windows and Daylight Savings. This affects the 'atime' and 'mtime' elements returned by stat[], and it also affects other filesystem-related functions such as fileatime[] and filemtime[].
During the winter months [when Daylight Savings isn't in effect], Windows will report a certain timestamp for a given file. However, when summer comes and Daylight Savings starts, Windows will report a DIFFERENT timestamp! Even if the file hasn't been altered at all, Windows will shift every timestamp it reads forward one full hour during Daylight Savings.
This all stems from the fact that M$ decided to use a hackneyed method of tracking file dates to make sure there are no ambiguous times during the "repeated hour" when DST ends in October, maintain compatibility with older FAT partitions, etc. An excellent description of what/why this is can be found at //www.codeproject.com/datetime/dstbugs.asp
This is noteworthy because *nix platforms don't have this problem. This could introduce some hard-to-track bugs if you're trying to move scripts that track file timestamps between platforms.
I spent a fair amount of time trying to debug one of my own scripts that was suffering from this problem. I was storing file modification times in a MySQL table, then using that information to see which files had been altered since the last run of the script. After each Daylight Savings change, every single file the script saw was considered "changed" since the last run, since all the timestamps were off by +/- 3600 seconds.
This one-liner is probably one of the most incorrect fixes that could ever be devised, but it's worked flawlessly in production-grade environments... Assuming $file_date is a Unix timestamp you've just read from a file:
That will ensure that the timestamp you're working with is always consistently reported, regardless of whether the machine is in Daylight Savings or not.
mao at nospam dot com ¶
17 years ago
If you have ftp [and the related sftp] protocols disabled on your remote server, it can be hard figuring out how to 'stat' a remote file. The following works for me:
salisbm at hotmail dot com ¶
19 years ago
I was curious how I could tell if a file was a directory... so I found on //www.hmug.org/man/2/stat.html the following information about the mode bits:
#define S_IFMT 0170000 /* type of file */
#define S_IFIFO 0010000 /* named pipe [fifo] */
#define S_IFCHR 0020000 /* character special */
#define S_IFDIR 0040000 /* directory */
#define S_IFBLK 0060000 /* block special */
#define S_IFREG 0100000 /* regular */
#define S_IFLNK 0120000 /* symbolic link */
#define S_IFSOCK 0140000 /* socket */
#define S_IFWHT 0160000 /* whiteout */
#define S_ISUID 0004000 /* set user id on execution */
#define S_ISGID 0002000 /* set group id on execution */
#define S_ISVTX 0001000 /* save swapped text even after use */
#define S_IRUSR 0000400 /* read permission, owner */
#define S_IWUSR 0000200 /* write permission, owner */
#define S_IXUSR 0000100 /* execute/search permission, owner */
Note that these numbers are in octal format. Then, to check to see if the file is a directory, after calling fstat, I do:
if [$fstats[mode] & 040000]
... this must be a directory
ian at eiloart dot com ¶
23 years ago
Here's what the UNIX man page on stat has to say about the difference between a file change and a file modification:
st_mtime Time when data was last modified. Changed by the following functions: creat[], mknod[], pipe[], utime[], and write[2].
st_ctime Time when file status was last changed. Changed by the following functions: chmod[], chown[], creat[], link[2], mknod[], pipe[], unlink[2], utime[], and write[].
So a modification is a change in the data, whereas a change also happens if you modify file permissions and so on.
digitalaudiorock at hotmail dot com ¶
13 years ago
Regarding the stat[] on files larger than 2GB on 32 bit systems not working, note that the behavior appears to differ between Linux and Windows. Under Windows there's so way to know whether or not this failed.
It's been my experience that under Linux, performing a stat[] on files that are too large for the integer size generates a warning and returns false. However under Windows it silently truncates the high order bits of the size resulting in an incorrect number. The only way you'd ever know it failed is in the event that the truncation happened to leave the sign bit on resulting in a negative size. That is, there is _no_ reliable way to know it failed.
This is true of filesize[] as well.
Tom
mail4rico at gmail dot com ¶
14 years ago
In response to the note whose first line is:
Re note posted by "admin at smitelli dot com"
I believe you have the conversion backwards. You should add an hour to filemtime if the system is in DST and the file is not. Conversely, you should subtract an hour if the file time is DST and the current OS time is not.
Here's a simplified, corrected version:
Here's a test:
Output:
------------------------------
[when run in summer]
------------------------------
Date0 [ST]: Tuesday, 01-Jan-08 10:00:00 EST
Date1 [DT]: Friday, 01-Aug-08 10:00:00 EDT
Uncorrected:
File 0: -3600
File 1: 0
Corrected:
File 0: 0
File 1: 0
------------------------------
[when run in winter--dates omitted]
------------------------------
Uncorrected:
File 0: 0
File 1: 3600
Corrected:
File 0: 0
File 1: 0
In response to Re note posted by "admin at smitelli dot com", your version below gives the following output when substituted into my test:
------------------------------
[when run in summer--dates omitted]
------------------------------
Uncorrected:
File 0: -3600
File 1: 0
Corrected:
File 0: -7200
File 1: 0
------------------------------
You can see that the operation is the opposite of what it should be.
com dot gmail at algofoogle ¶
17 years ago
Re note posted by "salisbm at hotmail dot com":
S_IFDIR is not a single-bit flag. It is a constant that relies on the "S_IFMT" bitmask. This bitmask should be applied to the "mode" parameter before comparing with any of the other "S_IF..." constants, as indicated by stat.h:
#define S_ISDIR[m] [[[m] & S_IFMT] == S_IFDIR]
That is, this approach is incorrect:
...and should instead be:
As pointed out by "svend at svendtofte dot com", however, there is also the "is_dir" function for this purpose, along with "is_file" and "is_link" to cover the most common format types...
marting.dc AT gmail.com ¶
16 years ago
If you want to know a directory size, this function will help you:
JulieC ¶
15 years ago
The dir_size function provided by "marting.dc AT gmail.com" works great, except the $mas variable is not initialized. Add:
$mas = 0;
before the while[] loop.
svend at svendtofte dot com ¶
17 years ago
To the note of how you can figure out if a file is a folder or not, there is also the handy "is_dir" function.
Hellhound ¶
14 years ago
To ignore index number or name specifics.. use:
list[$dev, $ino, $mode, $nlink, $uid, $gid, $rdev, $size, $atime, $mtime, $ctime, $blksize, $blocks]
= lstat[$directory_element];
carlos [at] encore-lab [dot] com ¶
7 years ago
stat[] may not work on mounted CIFS' in 32 bit systems if you do not specify the option noserverino when mounting. E.g:
mount -t cifs -o user="user",password="password",noserverino //example.local/share /mnt/mount-point
Other functions based on stat[] data such as file time functions and is_dir[] are affected the same way.
This happens because if you do not specify the option noserverino the remote inode may be 64 bit-based and thus the local system cannot handle it.
Anonymous ¶
16 years ago
Re note posted by "admin at smitelli dot com"
I'm not sure how that can work all year round since you have to modify both opposing inside and outside DST based on the actual files themselves, as well as the current DST setting for the system.
e.g. using filemtime, same thing for stat.
Just another example of why 'not' to use windows in a server room.
antonixyz at gmx dot net ¶
14 years ago
is identical to:
at least on my linux box.
Anonymous ¶
17 years ago
If the 2GB limit is driving you crazy, you can use this complete hack. use in place of filesize[]
function file_size[$file] {
$size = filesize[$file];
if [ $size == 0]
$size = exec["ls -l $file | awk '{print $5}'"];
return $size;
}