STAT(2)

名称
stat, lstat, fstat - ファイルステータスの取得

ライブラリ
libc

書式
<sys/types.h> <sys/stat.h> int stat(const char *path, struct stat *sb) int lstat(const char *path, struct stat *sb) int fstat(int fd, struct stat *sb)

解説
stat() システムコールは、 path が指すファイルの情報を取得します。 指定したファイルの読取り権、書込み権、実行権は必要ありません。 しかし、そのファイルへ至るパス名で列挙されたすべてのディレクトリは、 検索可能であることが必要です。

lstat() 関数は stat() に似ていますが、指定したファイルがシンボリックリンクである場合は異なります。 lstat() はリンクの情報を戻しますが、 stat() はリンクが参照するファイルの情報を返します。

fstat() システムコールは、ファイル記述子 fd で区別されるオープンファイルについて、上と同じ情報を取得します。

引数 sb は、構造体 stat へのポインタです。 これは、 <sys/stat.h> で定義され、ファイルに関する情報を保持します。

ファイルシステムに関連する struct stat のフィールドは以下のとおりです:

st_dev
    ファイルを含むデバイスの数値 ID。

st_ino
    ファイルの i ノード番号。

st_nlink
    ファイルへのハードリンクの数。

st_dev と st_ino フィールドはともにシステム中で唯一のファイルを特定します。

struct stat の時刻に関するフィールドは、以下のとおりです:

st_atime
    ファイルのデータが最後にアクセスされた時刻。 mknod(2), utimes(2), read(2) および readv(2) システムコールで変更されます。

st_mtime
    ファイルのデータが最後に修正された時刻。 mkdir(2), mkfifo(2), mknod(2), utimes(2), write(2) および writev(2) システムコールで変更されます。

st_ctime
    ファイルステータスが最後に変更された時刻 (inode データの修正)。 chflags(2), chmod(2), chown(2), creat(2), link(2), mkdir(2), mkfifo(2), mknod(2), rename(2), rmdir(2), symlink(2), truncate(2), unlink(2), utimes(2), write(2) および writev(2) システムコールで変更されます。

st_birthtime
    inode が作成されたときの時刻。

_POSIX_SOURCE が定義されていない場合、時刻に関するフィールドは以下のように定義されます:

    #ifndef _POSIX_SOURCE
    #define st_atime st_atimespec.tv_sec
    #define st_mtime st_mtimespec.tv_sec
    #define st_ctime st_ctimespec.tv_sec
    #endif

struct stat のサイズに関するフィールドは、以下のとおりです:

st_size
    バイトで表されるファイルサイズ。

st_blksize
    ファイルの最適な入出力ブロックサイズ。

st_blocks
    ファイルに 512 バイト単位で割り当てられたブロックの実際の数。 短いシンボリックリンクが inode に保持されている場合、この数値が 0 になることがあります。

struct stat のアクセス関連のフィールドは以下のとおりです:

st_uid
    ファイルの所有者のユーザID。

st_gid
    ファイルのグループID。

st_mode
    ファイルの状態 (下記参照)。

ステータス情報ワード st_mode には、以下のようなビットがあります:

    #define S_IFMT   0170000  /* ファイルのタイプ */
    #define S_IFIFO  0010000  /* 名前付きパイプ (fifo) */
    #define S_IFCHR  0020000  /* キャラクタ型特殊ファイル */
    #define S_IFDIR  0040000  /* ディレクトリ */
    #define S_IFBLK  0060000  /* ブロック型特殊ファイル */
    #define S_IFREG  0100000  /* 通常 */
    #define S_IFLNK  0120000  /* シンボリックリンク */
    #define S_IFSOCK 0140000  /* ソケット */
    #define S_IFWHT  0160000  /* ホワイトアウト */
    #define S_ISUID  0004000  /* 実行時にユーザ ID を設定 */
    #define S_ISGID  0002000  /* 実行時にグループ ID を設定 */
    #define S_ISVTX  0001000  /* 使用後にもスワップされたテキストを保存 */
    #define S_IRUSR  0000400  /* 読取り権限の所有者 */
    #define S_IWUSR  0000200  /* 書込み権限の所有者 */
    #define S_IXUSR  0000100  /* 実行 / 検索権限の所有者 */

アクセスモードのリストについては、 <sys/stat.h>, access(2), chmod(2) を参照してください。 以下のマクロは m 引数で渡された st_mode 値が指定されたタイプのファイルに対応しているかどうか テストするために利用可能です:

S_ISBLK(m)
    ブロック特殊ファイルかどうかテストする。

S_ISCHR(m)
    キャラクタ特殊ファイルかどうかテストする。

S_ISDIR(m)
    ディレクトリかどうかテストする。

S_ISFIFO(m)
    パイプか FIFO 特殊ファイルかどうかテストする。

S_ISLNK(m)
    シンボリックリンクかどうかテストする。

S_ISREG(m)
    通常のファイルかどうかテストする。

S_ISSOCK(m)
    ソケットかどうかテストする。

S_ISWHT(m)
    ホワイトアウトかどうかテストする。

マクロは、テストが真なら 0 以外、またはテストが偽なら 0 に評価します。

戻り値

互換性
以前のバージョンのシステムでは、 st_dev, st_uid, st_gid, st_rdev, st_size, st_blksize, st_blocks フィールドに別のタイプを使用していました。

エラー
stat() システムコールと lstat() システムコールは、以下のような場合にエラーとなります:

[EACCES]
    指定されたパスには、検索が許可されていないディレクトリが含まれています。

[EFAULT]
    sb 引数または path 引数は、プロセスに割り当てられたアドレス空間の範囲外を指しています。

[EIO]
    ファイルシステムでの読み書き中に入出力エラーが発生しました。

[ELOOP]
    パス名を変換するときに検出されたシンボリックリンクが多すぎます。

[ENAMETOOLONG]
    パス名の構成要素が 255 文字を越えているか、 またはパス名全体が 1023 文字を越えています。

[ENOENT]
    指定されたファイルが存在しません。

[ENOTDIR]
    パスの構成要素中にディレクトリ以外のものが含まれています。

[EOVERFLOW]
    ファイルサイズのバイト数が、 sb で指されている構造体で正しく表現できません。

fstat() システムコールは、以下のような場合にエラーとなります:

[EBADF]
    fd 引数が、有効な記述子ではありません。

[EFAULT]
    sb 引数が、プロセスに割り当てられたアドレス空間の範囲外を指しています。

[EIO]
    ファイルシステムに読み書きしている間に入出力エラーが発生しました。

[EOVERFLOW]
    ファイルサイズのバイト数が、 sb で指されている構造体で正しく表現できません。

関連項目
access(2), chmod(2), chown(2), utimes(2), symlink(7), sticky(8)

バグ
fstat() をソケット (およびパイプ) に適用すると、ブロックサイズフィールド、 および固有デバイスと inode 番号以外に 0 の入ったバッファが戻されます。

規格
stat() システムコールと fstat() システムコールは、 p1003.1-90 に適合しています。

歴史
stat() システムコールと fstat() システムコールは、 AT&T UNIX で登場しました。 lstat() システムコールは 4.2BSD で登場しました。