stat

(PHP 4, PHP 5, PHP 7, PHP 8)

statSammelt Informationen über eine Datei

Beschreibung

stat(string $filename): array|false

Sammelt Statistiken über die per filename angegebene Datei. Falls filename ein symbolischer Link ist, beziehen sich die Statistiken auf die Datei selbst, nicht auf den symbolischen Link. Unter Windows NTS-Builds vor PHP 7.4.0 bezogen sich in diesem Fall die size-, atime-, mtime- und ctime-Statistiken auf den symbolischen Link.

lstat() ist identisch zu stat(), mit dem Unterschied, dass es sich auf den Status des symbolischen Links bezieht.

Parameter-Liste

filename

Pfad zur Datei.

Rückgabewerte

stat()- und fstat()-Ergebnisformat
Numerisch Assoziativ Beschreibung
0 dev Gerätenummer ***
1 ino Inode-Nummer ****
2 mode Inode-Schutzmodus *****
3 nlink Anzahl der Links
4 uid userid des Besitzers *
5 gid groupid des Besitzers *
6 rdev Gerätetyp, falls Inode-Gerät
7 size Größe in Bytes
8 atime Zeitpunkt des letzten Zugriffs (Unix-Timestamp)
9 mtime Zeitpunkt der letzten Änderung (Unix-Timestamp)
10 ctime Zeitpunkt der letzten Inode-Änderung (Unix-Timestamp)
11 blksize Blockgröße des Dateisystem-I/O **
12 blocks Anzahl der zugewiesenen 512-Byte-Blöcke **

* Unter Windows wird dies immer 0 sein.

** Nur gültig unter Systemen, die den st_blksize-Typ unterstützen - andere Systeme (z. B. Windows) geben -1 zurück.

*** Unter Windows, von PHP 7.4.0 an, ist dies die Seriennummer des Laufwerks, das die Datei enhält, welches eine 64-bit Ganzzahl ohne Vorzeichen ist, so dass auf 32-bit-Systemen ein Überlauf erfolgen kann. Zuvor war es die numerische Darstellung des Laufwerksbuchstabens (z. B. 2 für C:) für stat(), und 0 für lstat().

**** Unter Windows, von PHP 7.4.0 an, ist dies die mit der Datei assozierte Kennung, welche eine 64-bit Ganzzahl ohne Vorzeichen ist, so dass ein Überlauf erfolgen kann. Zuvor war es immer 0.

***** Unter Windows wird das Schreibberechtigungsbit entsprechend dem schreibgeschützten Dateiattribut gesetzt, und derselbe Wert wird für alle Benutzer, Gruppen und Besitzer gemeldet. Die ACL wird im Gegensatz zu is_writable() nicht berücksichtigt.

Der Wert von mode enthält Informationen, die von mehreren Funktionen gelesen werden. Wenn als Oktalzahl dargestellt und von rechts betrachtet, werden die ersten drei Ziffern von chmod() zurückgegeben. Die nächste Ziffer wird von PHP ignoriert. Die nächsten beiden Ziffern geben den Dateityp an:

mode Dateitypen
mode als Oktalzahl Bedeutung
0140000 socket
0120000 Verknüpfung
0100000 reguläre Datei
0060000 Block-Gerät
0040000 Verzeichnis
0020000 zeichenorientiertes Gerät
0010000 FIFO
So könnte beispielsweise eine reguläre Datei 0100644, und ein Verzeichnis 0040755 sein.

Im Fehlerfall gibt stat() false zurück.

Hinweis: Weil PHPs Integer Typ vorzeichenbehaftet ist und viele Platformen 32bit Integer verwenden, können einige Dateisystem-Funktionen für Dateien größer als 2GB unerwartete Ergebnisse liefern.

Fehler/Exceptions

Im Fehlerfall wird eine E_WARNING geworfen.

Changelog

Version Beschreibung
7.4.0 Unter Windows ist die Gerätenummer nun die Seriennummer des Laufwerks, das die Datei enthält, und die Inode-Nummer ist die mit der Datei assozierte Kennung.
7.4.0 Die size-, atime-, mtime- und ctime-Statistiken symbolischer Links sind nun immer die des Ziels. Dies war zuvor nicht der Fall für NTS-Builds unter Windows.

Beispiele

Beispiel #1 stat()-Beispiel

<?php
/* Hole Datei-Statistik */
$stat = stat('C:\php\php.exe');

/*
* Gebe den Zugriffszeitpunkt der Datei aus; dies entspricht dem
* Aufruf von fileatime()
*/
echo 'Zugriffszeitpunkt: ' . $stat['atime'];

/*
* Gebe den Änderungszeitpunkt der Datei aus; dies entspricht dem
* Aufruf von filemtime()
*/
echo 'Änderungszeitpunkt: ' . $stat['mtime'];

/* Gebe die Gerätenummer aus */
echo 'Gerätenummer: ' . $stat['dev'];
?>

Beispiel #2 Nutzung von stat()-Informationen zusammen mit touch()

<?php
/* Hole Datei-Statistik */
$stat = stat('C:\php\php.exe');

/* Hat das Holen der Statistik-Informationen geklappt? */
if (!$stat) {
echo
'stat()-Aufruf schlug fehl ...';
} else {
/*
* Wir wollen den Zugriffszeitpunkt auf eine Woche nach dem aktuellen
* Zugriffszeitpunkt setzen.
*/
$atime = $stat['atime'] + 604800;

/* Ändere die Datei */
if (!touch('eine_datei.txt', time(), $atime)) {
echo
'Ändern der Datei schlug fehl ...';
} else {
echo
'touch()-Befehl war erfolgreich ...';
}
}
?>

Anmerkungen

Hinweis:

Beachten Sie, dass die zeitliche Auflösung bei verschiedenen Dateisystemen unterschiedlich sein kann.

Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

Siehe auch

  • lstat() - Sammelt Informationen über eine Datei oder einen symbolischen Link
  • fstat() - Sammelt Informationen über eine Datei mittels eines offenen Dateizeigers
  • filemtime() - Liefert die Zeit der letzten Dateiänderung
  • filegroup() - Liefert die Gruppenzugehörigkeit einer Datei
  • SplFileInfo

add a note add a note

User Contributed Notes 18 notes

up
11
webmaster at askapache dot com
10 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.

<?php

/**
* Returns the number of running processes
*
* @link http://php.net/clearstatcache
* @link http://php.net/stat  Description of stat syntax.
* @author http://www.askapache.com/php/get-number-running-proccesses.html
* @return int
*/
function get_process_count() {
  static
$ver, $runs = 0;
 
 
// check if php version supports clearstatcache params, but only check once
 
if ( is_null( $ver ) )
   
$ver = version_compare( PHP_VERSION, '5.3.0', '>=' );

 
// Only call clearstatcache() if function called more than once */
 
if ( $runs++ > 0 ) { // checks if $runs > 0, then increments $runs by one.
   
    // if php version is >= 5.3.0
   
if ( $ver ) {
     
clearstatcache( true, '/proc' );
    } else {
     
// if php version is < 5.3.0
     
clearstatcache();
    }
  }
 
 
$stat = stat( '/proc' );

 
// if stat succeeds and nlink value is present return it, otherwise return 0
 
return ( ( false !== $stat && isset( $stat[3] ) ) ? $stat[3] : 0 );
}

?>

Example #1 get_process_count() example

<?php
$num_procs
= get_process_count();
var_dump( $num_procs );
?>

The above example will output:

int(118)

Which is the number of processes that were running.
up
9
webmaster at askapache dot com
15 years ago
This is a souped up 'stat' function based on
many user-submitted code snippets and
@ http://www.askapache.com/security/chmod-stat.html

Give it a filename, and it returns an array like stat.

<?php

function alt_stat($file) {

clearstatcache();
$ss=@stat($file);
if(!
$ss) return false; //Couldnt stat file

$ts=array(
 
0140000=>'ssocket',
 
0120000=>'llink',
 
0100000=>'-file',
 
0060000=>'bblock',
 
0040000=>'ddir',
 
0020000=>'cchar',
 
0010000=>'pfifo'
);

$p=$ss['mode'];
$t=decoct($ss['mode'] & 0170000); // File Encoding Bit

$str =(array_key_exists(octdec($t),$ts))?$ts[octdec($t)]{0}:'u';
$str.=(($p&0x0100)?'r':'-').(($p&0x0080)?'w':'-');
$str.=(($p&0x0040)?(($p&0x0800)?'s':'x'):(($p&0x0800)?'S':'-'));
$str.=(($p&0x0020)?'r':'-').(($p&0x0010)?'w':'-');
$str.=(($p&0x0008)?(($p&0x0400)?'s':'x'):(($p&0x0400)?'S':'-'));
$str.=(($p&0x0004)?'r':'-').(($p&0x0002)?'w':'-');
$str.=(($p&0x0001)?(($p&0x0200)?'t':'x'):(($p&0x0200)?'T':'-'));

$s=array(
'perms'=>array(
 
'umask'=>sprintf("%04o",@umask()),
 
'human'=>$str,
 
'octal1'=>sprintf("%o", ($ss['mode'] & 000777)),
 
'octal2'=>sprintf("0%o", 0777 & $p),
 
'decimal'=>sprintf("%04o", $p),
 
'fileperms'=>@fileperms($file),
 
'mode1'=>$p,
 
'mode2'=>$ss['mode']),

'owner'=>array(
 
'fileowner'=>$ss['uid'],
 
'filegroup'=>$ss['gid'],
 
'owner'=>
  (
function_exists('posix_getpwuid'))?
  @
posix_getpwuid($ss['uid']):'',
 
'group'=>
  (
function_exists('posix_getgrgid'))?
  @
posix_getgrgid($ss['gid']):''
 
),

'file'=>array(
 
'filename'=>$file,
 
'realpath'=>(@realpath($file) != $file) ? @realpath($file) : '',
 
'dirname'=>@dirname($file),
 
'basename'=>@basename($file)
  ),

'filetype'=>array(
 
'type'=>substr($ts[octdec($t)],1),
 
'type_octal'=>sprintf("%07o", octdec($t)),
 
'is_file'=>@is_file($file),
 
'is_dir'=>@is_dir($file),
 
'is_link'=>@is_link($file),
 
'is_readable'=> @is_readable($file),
 
'is_writable'=> @is_writable($file)
  ),
 
'device'=>array(
 
'device'=>$ss['dev'], //Device
 
'device_number'=>$ss['rdev'], //Device number, if device.
 
'inode'=>$ss['ino'], //File serial number
 
'link_count'=>$ss['nlink'], //link count
 
'link_to'=>($s['type']=='link') ? @readlink($file) : ''
 
),

'size'=>array(
 
'size'=>$ss['size'], //Size of file, in bytes.
 
'blocks'=>$ss['blocks'], //Number 512-byte blocks allocated
 
'block_size'=> $ss['blksize'] //Optimal block size for I/O.
 
),

'time'=>array(
 
'mtime'=>$ss['mtime'], //Time of last modification
 
'atime'=>$ss['atime'], //Time of last access.
 
'ctime'=>$ss['ctime'], //Time of last status change
 
'accessed'=>@date('Y M D H:i:s',$ss['atime']),
 
'modified'=>@date('Y M D H:i:s',$ss['mtime']),
 
'created'=>@date('Y M D H:i:s',$ss['ctime'])
  ),
);

clearstatcache();
return
$s;
}

?>

|=---------[ 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
  )
)
up
8
admin at smitelli dot com
18 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 http://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:

<?php
   
if (date('I') == 1) $file_date -= 3600;
?>

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.
up
4
mao at nospam dot com
18 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:

<?php 

$conn
= ssh2_connect($host, 22);
ssh2_auth_password($conn, $user, $password);
$stream = ssh2_exec($conn, "stat $fileName > $remotedest");
ssh2_scp_recv($conn, $remotedest, $localdest);
$farray = file($localdest);
print_r($farray);
?>
up
7
salisbm at hotmail dot com
20 years ago
I was curious how I could tell if a file was a directory... so I found on http://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
up
3
ian at eiloart dot com
24 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.
up
4
digitalaudiorock at hotmail dot com
15 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
up
4
mail4rico at gmail dot com
15 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:
<?php
   
function getmodtime($file) { //returns the time a file was modified.
       
$mtime = filemtime($file);
       
//date('I') returns 1 if DST is on and 0 if off.
       
$diff = date('I')-date('I', $mtime);
       
//diff =  0 if file-time and os-time are both in the same DST setting
        //diff =  1 if os is DST and file is not
        //diff = -1 if file is DST and os is not
       
return $mtime + $diff*3600;
    }
?>
Here's a test:
<?php
   
//create two dummy files:
   
$file0 = 'file1.txt';
   
$file1 = 'file2.txt';
   
file_put_contents($file0, '');
   
file_put_contents($file1, '');
   
   
$time0=strtotime('Jan 1 2008 10:00'); echo 'Date0 (ST): ' . date(DATE_COOKIE, $time0)."\n";
   
$time1=strtotime('Aug 1 2008 10:00'); echo 'Date1 (DT): ' . date(DATE_COOKIE, $time1)."\n";
   
touch($file0, $time0); //set file0 to Winter (Non-DST)
   
touch($file1, $time1); //set file1 to Summer (DST)
   
   
$ftime0 = filemtime($file0);
   
$ftime1 = filemtime($file1);
    echo
"\nUncorrected: \n";
    echo
'File 0: ' . ($ftime0-$time0) ."\n";
    echo
'File 1: ' . ($ftime1-$time1) ."\n";
   
//if your system adjusts for DST, then _one_ of the above should be 3600 or -3600, depending on the time of year
   
   
$ftime0 = getmodtime($file0); //use filemtime correction
   
$ftime1 = getmodtime($file1); //use filemtime correction
   
echo "\nCorrected: \n";
    echo
'File 0: ' . ($ftime0-$time0) ."\n";
    echo
'File 1: ' . ($ftime1-$time1) ."\n";
   
//both of the corrected values output should be 0.
?>

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.
up
4
com dot gmail at algofoogle
18 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:

<?php
define
('S_IFDIR',040000);
if (
$mode & S_IFDIR)
{
 
/*
    incorrect!
    format could be S_IFDIR, but also
    S_IFBLK, S_IFSOCK, or S_IFWHT.
  */
}
?>

...and should instead be:

<?php
define
('S_IFMT',0170000);
define('S_IFDIR',040000);
if (
S_IFDIR == ($mode & S_IFMT)) {  /* ... */  }
?>

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...
up
3
marting.dc AT gmail.com
18 years ago
If you want to know a directory size, this function will help you:

<?php
function dir_size($dir)
{
   
$handle = opendir($dir);
   
    while (
$file = readdir($handle)) {
        if (
$file != '..' && $file != '.' && !is_dir($dir.'/'.$file)) {
           
$mas += filesize($dir.'/'.$file);
            } else if (
is_dir($dir.'/'.$file) && $file != '..' && $file != '.') {
           
$mas += dir_size($dir.'/'.$file);
        }
    }
    return
$mas;
}
echo
dir_size('DIRECTORIO').' Bytes';
?>
up
2
JulieC
17 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.
up
2
svend at svendtofte dot com
19 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.
up
1
Hellhound
16 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);
up
1
Ray.Paseur sometimes uses Gmail
3 years ago
A good explanation of the "mode" bits is given here:
https://www.php.net/manual/en/function.fileperms.php
up
0
carlos [at] encore-lab [dot] com
9 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.
up
0
Anonymous
17 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.

<?php

$mtime
= filemtime($file);

if (
date('I') == 1) {
   
// Win DST is enabled, adjust standard time
    // files back to 'real' file UTC.
   
if (date('I', $mtime) == 0) {
       
$mtime -= 3600;
    }
} else {
   
// Win DST is disabled, adjust daylight time
    // files forward to 'real' file UTC.
   
if (date('I', $mtime) == 1) {
       
$mtime += 3600;
    }
}

echo
gmdate('Y-m-d H:i:s', $mtime);

?>

Just another example of why 'not' to use windows in a server room.
up
-2
antonixyz at gmx dot net
15 years ago
<?php
$stat
= stat($filepath);
$mode = $stat[2];
?>
is identical to:
<?php $mode = fileperms($filepath); ?>

at least on my linux box.
up
-3
Anonymous
19 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;
}
To Top