stat

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

statファイルに関する情報を取得する

説明

stat(string $filename): array|false

filenameで指定されたファイルに ついての統計情報を取得します。 filename がシンボリックリンクの場合、 シンボリックリンクではなくファイルの実体の統計情報が返されます。 Windows 環境、かつ PHP 7.4.0 より前の NTS ビルドでは、 size, atime, mtime, ctime の統計情報は、シンボリックリンクの値が返されていました。

lstat() はシンボリックリンクの統計情報を返すという違いを除いて stat() と等価です。

パラメータ

filename

ファイルへのパス。

戻り値

stat()fstat() の結果のフォーマット
数値 連想配列 説明
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 のファイルタイプ
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

関連キーワード:  情報, 取得, stat, 関数, デバイス, ファイル, 統計, inode, 番号, mode