stat
(PHP 4, PHP 5, PHP 7, PHP 8)
stat — ファイルに関する情報を取得する
説明
filename
で指定されたファイルに
ついての統計情報を取得します。
filename
がシンボリックリンクの場合、
シンボリックリンクではなくファイルの実体の統計情報が返されます。
Windows 環境、かつ PHP 7.4.0 より前の NTS ビルドでは、
size
,
atime
, mtime
, ctime
の統計情報は、シンボリックリンクの値が返されていました。
lstat() はシンボリックリンクの統計情報を返すという違いを除いて stat() と等価です。
パラメータ
filename
-
ファイルへのパス。
戻り値
数値 | 連想配列 | 説明 |
---|---|---|
0 | dev | デバイス番号 (***) |
1 | ino | inode 番号(****) |
2 | mode | inode プロテクトモード(*****) |
3 | nlink | リンク数 |
4 | uid | 所有者のユーザー ID(*) |
5 | gid | 所有者のグループ ID(*) |
6 | rdev | inode デバイス の場合、デバイスの種類 |
7 | size | バイト単位のサイズ |
8 | atime | 最終アクセス時間 (Unix タイムスタンプ) |
9 | mtime | 最終修正時間 (Unix タイムスタンプ) |
10 | ctime | 最終 inode 変更時間 (Unix タイムスタンプ) |
11 | blksize | ファイル IO のブロックサイズ(**) |
12 | blocks | 512 バイトのブロックの確保数(**) |
* Windows では常に 0
となります。
** st_blksize タイプをサポートするシステムでのみ有効です。
その他のシステム(例えば Windows)では -1
を返します。
*** PHP 7.4.0 以降、Windows では、この値はファイルが含まれるボリュームのシリアル番号です。
これは64ビットの 符号なし 整数です。
よって、オーバーフローする可能性があります。
これより前のバージョンでは、stat() 関数ではドライブレターを数値で表現した値
(たとえば、C:
では 2
) でした。
lstat() 関数では 0
でした。
**** PHP 7.4.0 以降、Windows では、この値はファイルに関連付けられた識別子です。
これは64ビットの 符号なし 整数です。
よって、オーバーフローする可能性があります。
これより前のバージョンでは、この値は常に 0
でした。
***** Windows では、 読み取り専用のファイル属性に従って、 書き込み可能のパーミッションビットが設定されます。 そして、この値は全てのユーザ、グループ、 オーナーについて、同じ値が報告されます。 is_writable() とは異なり、ACL は考慮されません。
mode
の値は、複数の関数によって読まれる情報が含まれています。
8進数の場合、一番右の桁から評価され、はじめの3桁が chmod() によって返されます。
次の桁は PHP によって無視されます。その次の2桁は以下のファイルタイプを示します:
mode が8進数だった場合 |
意味 |
---|---|
0140000 |
ソケット |
0120000 |
リンク |
0100000 |
通常のファイル |
0060000 |
ブロックデバイス |
0040000 |
ディレクトリ |
0020000 |
キャラクタデバイス |
0010000 |
fifo |
0100644
のような値になりますし、
ディレクトリは 0040755
のような値になります。
stat() はエラーの場合 false
を返します。
注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。
エラー / 例外
失敗した場合は E_WARNING
が発生します。
変更履歴
バージョン | 説明 |
---|---|
7.4.0 | Windows では、 デバイス番号は、ファイルが含まれるボリュームのシリアル番号を返すようになりました。 そして、inode 番号は、ファイルに関連付けられた識別子を返すようになりました。 |
7.4.0 |
シンボリックリンクの場合、
size , atime , mtime ,
ctime の統計情報は、ファイルの実体の値が返されるようになりました。
これより前のバージョンの Windows NTS ビルドはそうではありませんでした。
|
例
例1 stat() の例
<?php
/* ファイルの状態を取得します */
$stat = stat('C:\php\php.exe');
/*
* ファイルのアクセス日時を表示します。
* これは fileatime() をコールするのと同じです
*/
echo 'アクセス日時: ' . $stat['atime'];
/*
* ファイルの更新日時を表示します。
* これは filemtime() をコールするのと同じです
*/
echo '更新日時: ' . $stat['mtime'];
/* デバイス番号を表示します */
echo 'デバイス番号: ' . $stat['dev'];
?>
例2 stat() の情報を touch() と組み合わせる例
<?php
/* ファイルの状態を取得します */
$stat = stat('C:\php\php.exe');
/* 情報の取得に失敗した? */
if (!$stat) {
echo 'stat() のコールに失敗しました...';
} else {
/*
* アクセス日時を、現在のアクセス日時の
* 一週間後に設定します
*/
$atime = $stat['atime'] + 604800;
/* ファイルを作成します */
if (!touch('some_file.txt', time(), $atime)) {
echo 'ファイルの作成に失敗しました...';
} else {
echo 'touch() が成功しました...';
}
}
?>
注意
注意:
時刻の精度は、 ファイルシステムによって異なることがあります。
注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。
PHP 5.0.0
以降、この関数は、
何らかの URL ラッパーと組合せて使用することができます。
どのラッパーが stat() ファミリーをサポートしているかを調べるには
サポートするプロトコル/ラッパー を参照してください。
参考
- lstat() - ファイルあるいはシンボリックリンクの情報を取得する
- fstat() - オープンしたファイルポインタからファイルに関する情報を取得する
- filemtime() - ファイルの更新時刻を取得する
- filegroup() - ファイルのグループを取得する
- SplFileInfo
User Contributed Notes 18 notes
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
)
)
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.
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.
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.