FILEHANDLE か DIRHANDLE を通じてオープンされているファイルか、 EXPR で指定されるファイルの情報を与える、13 要素のリストを返します。 EXPR が省略されると、 $_ が用いられます (_ ではありません!)。 stat に失敗した場合には、空リストを返します。 普通は、以下のようにして使います:

    my ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
        $atime,$mtime,$ctime,$blksize,$blocks)
           = stat($filename);

全てのファイルシステムで全てのフィールドに対応しているわけではありません。 フィールドの意味は以下の通りです。

  0 dev      device number of filesystem
  1 ino      inode number
  2 mode     file mode  (type and permissions)
  3 nlink    number of (hard) links to the file
  4 uid      numeric user ID of file's owner
  5 gid      numeric group ID of file's owner
  6 rdev     the device identifier (special files only)
  7 size     total size of file, in bytes
  8 atime    last access time in seconds since the epoch
  9 mtime    last modify time in seconds since the epoch
 10 ctime    inode change time in seconds since the epoch (*)
 11 blksize  preferred I/O size in bytes for interacting with the
             file (may vary from file to file)
 12 blocks   actual number of system-specific blocks allocated
             on disk (often, but not always, 512 bytes each)

  0 dev      ファイルシステムのデバイス番号
  1 ino      inode 番号
  2 mode     ファイルモード (タイプとパーミッション)
  3 nlink    ファイルへの(ハード)リンクの数
  4 uid      ファイル所有者のユーザー ID の数値
  5 gid      ファイル所有者のグループ ID の数値
  6 rdev     デバイス識別子(特殊ファイルのみ)
  7 size     ファイルサイズ(バイト単位)
  8 atime    紀元から、最後にアクセスされた時刻までの秒数
  9 mtime    紀元から、最後に修正(modify)された時刻までの秒数
 10 ctime    紀元から、inode 変更(change)された時刻までの秒数 (*)
 11 blksize  ファイルとの相互作用のために適した I/O バイト数
             (ファイルごとに異なるかもしれない)
 12 blocks   ディスクに割り当てたシステム依存のブロック(常にでは
             ありませんがたいていはそれぞれ 512 バイト)の数

(紀元は GMT で 1970/01/01 00:00:00。)

(*) 全てのフィールドが全てのファイルシステムタイプで対応しているわけでは ありません。 明らかに、ctime のフィールドは移植性がありません。 特に、これから「作成時刻」を想定することは出来ません; 詳細については "Files and Filesystems" in perlport を参照してください。

下線だけの _ という特別なファイルハンドルを stat に 渡すと、実際には stat を行なわず、stat 構造体に残っている 前回の stat, lstat や ファイルテストの情報が返されます。 例:

    if (-x $file && (($d) = stat(_)) && $d < 0) {
        print "$file is executable NFS file\n";
    }

(これは、NFS のもとでデバイス番号が負になるマシンでのみ動作します。)

一部のプラットフォームでは、inode 番号は perl が整数値として 扱い方を知っているものよりも大きい型になっています。 もし必要なら、inode 番号は、値全体を保存するために 10 進文字列として 返されます。 数値コンテキストで使うと、これは丸めを伴う浮動小数点数に変換され、 できるだけ避けるべき結果になります。 従って、inode 番号の比較には == ではなく eq を使うべきです。 eq は、inode 番号が数値で表現されていても、文字列で表現されていても うまく動作します。

モードにはファイルタイプとその権限の両方が含まれているので、 本当の権限を見たい場合は、(s)printf で "%" を使うことで ファイルタイプをマスクするべきです。

    my $mode = (stat($filename))[2];
    printf "Permissions are %04o\n", $mode & 07777;

スカラコンテキストでは、stat は成功か失敗を表す真偽値を 返し、成功した場合は、特別なファイルハンドル _ に結び付けられた 情報をセットします。

File::stat モジュールは、便利な名前によるアクセス機構を提供します。

    use File::stat;
    my $sb = stat($filename);
    printf "File is %s, size is %s, perm %04o, mtime %s\n",
           $filename, $sb->size, $sb->mode & 07777,
           scalar localtime $sb->mtime;

モード定数と関数 (S_I*) を Fcntl モジュールから インポートできます。

    use Fcntl ':mode';

    my $mode = (stat($filename))[2];

    my $user_rwx      = ($mode & S_IRWXU) >> 6;
    my $group_read    = ($mode & S_IRGRP) >> 3;
    my $other_execute =  $mode & S_IXOTH;

    printf "Permissions are %04o\n", S_IMODE($mode), "\n";

    my $is_setuid     =  $mode & S_ISUID;
    my $is_directory  =  S_ISDIR($mode);

最後の二つは -u と -d 演算子を使っても書けます。 一般に利用可能な S_I* 定数は以下のものです。

    # Permissions: read, write, execute, for user, group, others.

    S_IRWXU S_IRUSR S_IWUSR S_IXUSR
    S_IRWXG S_IRGRP S_IWGRP S_IXGRP
    S_IRWXO S_IROTH S_IWOTH S_IXOTH

    # Setuid/Setgid/Stickiness/SaveText/EnforcedLocks.
    # Note that the exact meaning of these is system-dependent.

    S_ISUID S_ISGID S_ISVTX S_ISTXT S_ENFMT

    # File types.  Not all are necessarily available on
    # your system.

    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
    S_IFIFO S_IFSOCK S_IFWHT

    # The following are compatibility aliases for S_IRUSR,
    # S_IWUSR, and S_IXUSR.

    S_IREAD S_IWRITE S_IEXEC

一般に利用可能な S_I* 関数は以下のものです。

    S_IMODE($mode)    the part of $mode containing the permission
                      bits and the setuid/setgid/sticky bits

    S_IFMT($mode)     the part of $mode containing the file type,
                      which will match one of the S_IF* constants
                      (e.g. S_IFMT($mode) == S_IFDIR for directories),
                      but see the following helper functions

    # The operators -f, -d, -l, -b, -c, -p, and -S.

    S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
    S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)

    # No direct -X operator counterpart, but for the first one
    # the -g operator is often equivalent.  The ENFMT stands for
    # record flocking enforcement, a platform-dependent feature.

    S_ISENFMT($mode) S_ISWHT($mode)

S_I* 定数に関する詳細についてはネイティブの chmod(2) と stat(2) の ドキュメントを参照してください。 リンクの先にあるファイルではなく、シンボリックリンクそのものの情報を 得たい場合は、lstat 関数を使ってください。

移植性の問題: "stat" in perlport。