stat

Gives information about a file

&reftitle.description; ``array``false```stat` `string` `filename`

Gathers the statistics of the file named by `filename`. If `filename` is a symbolic link, statistics are from the file itself, not the symlink. Prior to PHP 7.4.0, on Windows NTS builds the `size`, `atime`, `mtime` and `ctime` statistics have been from the symlink, in this case.

`lstat` is identical to `stat` except it would instead be based off the symlinks status.

&reftitle.parameters;

`filename`

- Path to the file.

&reftitle.returnvalues;

## `stat` and `fstat` result format

Numeric | Associative | Description
0 | 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 types

`mode` in octal | Meaning
`0140000` | 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;.

&fs.file.32bit;
&reftitle.errors;

Upon failure, an `E_WARNING` is emitted.

&reftitle.changelog;

&Version; | &Description;
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.

&reftitle.examples;

### `stat` example

    <?php
    /* Get file stat */
    $stat = stat('C:\php\php.exe');

    /*
     * Print file access time, this is the same
     * as calling fileatime()
     */
    echo 'Access time: ' . $stat['atime'];

    /*
     * Print file modification time, this is the
     * same as calling filemtime()
     */
    echo 'Modification time: ' . $stat['mtime'];

    /* Print the device number */
    echo 'Device number: ' . $stat['dev'];
    ?>

### Using `stat` information together with `touch`

    <?php
    /* Get file stat */
    $stat = stat('C:\php\php.exe');

    /* Did we failed to get stat information? */
    if (!$stat) {
        echo 'stat() call failed...';
    } else {
        /*
         * We want the access time to be 1 week
         * after the current access time.
         */
        $atime = $stat['atime'] + 604800;

        /* Touch the file */
        if (!touch('some_file.txt', time(), $atime)) {
            echo 'Failed to touch file...';
        } else {
            echo 'touch() returned success...';
        }
    }
    ?>

&reftitle.notes; ¬e.filesystem-time-res; ¬e.clearstatcache; &tip.fopen-wrapper.stat;
&reftitle.seealso;

- `lstat`
- `fstat`
- `filemtime`
- `filegroup`
- `SplFileInfo`