stat(2)

stat, lstat, fstat − ファイルステータスの取得

標準 C ライブラリ (libc, −lc)

#include <sys/types.h>
#include <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 のフィールドは以下のとおりです:

ファイルを含むデバイスの数値 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_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_ISCHR(m)
キャラクタ特殊ファイルかどうかテストする。

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

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

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

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

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

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

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

戻り値

成功して終了したときには値 0 を返します。そうでない場合、値 -1 が返され、 グローバル変数 errno が設定されてエラーを示します。

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

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

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

[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() システムコールは、 ISO/IEC 9945-1:1990 (‘‘POSIX.1’’) に適合しています。

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

FreeBSD 10.0 November 15, 2004 FreeBSD 10.0