STAT(2) | FreeBSD System Calls Manual | STAT(2) |
名称
stat, lstat, fstat, fstatat — ファイルのステータスを取得するライブラリ
Standard C Library (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);
int
fstatat( int fd, const char *path, struct stat *buf, int flag);
解説
stat() システムコールは、 path が指すファイルの情報を取得します。指定したファイルの読み込み権、書み込み権、実行権は、必要ありません。しかし、そのファイルへ至るパス名で列挙されたすべてのディレクトリは、検索可能であることが必要です。lstat() 関数は、 stat() に似ていますが、指定したファイルがシンボリックリンクである場合は、異なります。 lstat() は、リンクの情報を戻しますが、 stat() は、リンクが参照するファイルの情報を返します。
fstat() システムコールは、ファイル記述子 fd で区別されるオープンファイルについて、上と同じ情報を取得します。
fstatat() システムコールは、 path が相対パスを指定する場合を除いて、 stat() と lstat() と同等です。この場合、状態は、カレントワーキングディレクトリの代わりにファイル記述子 fd に関連しているディレクトリに相対的なファイルから検索されます。
flag のための値は、 < fcntl.h> で定義され、次のリストからフラブのビット単位の包括的論理和 (OR) によって構成されます:
- AT_SYMLINK_NOFOLLOW
- path 名がシンボリックリンクであるなら、シンボリックリンクの状態が返されます。
fstatat() が、 fd パラメータの特別な値 AT_FDCWD を渡されるなら、カレントワーキングディレクトリが、使用され、振る舞いは、 AT_SYMLINK_NOFOLLOW ビットが flag に設定されているかどうかにより、それぞれ stat() または lstat() への呼び出しと同じです。
sb 引数は、 stat 構造体へのポインタです。これは、 < sys/stat.h> で定義され、ファイルに関する情報を保持します。
ファイルシステムに関連する struct stat フィールドは、次の通りです:
- st_dev
- ファイルを含むデバイスの数値 ID。
- st_ino
- ファイルの i ノード番号。
- st_nlink
- ファイルへのハードリンクの数。
st_dev と st_ino フィールドは、ともにシステム中で唯一のファイルを特定します。
struct stat の時刻に関するフィールドは、次の通りです:
- st_atim
- ファイルのデータが最後にアクセスされた時刻。 mknod(2), utimes(2), read(2) と readv(2) システムコールで変更されます。
- st_mtim
- ファイルのデータが最後に修正された時刻。 mkdir(2), mkfifo(2), mknod(2), utimes(2), write(2) と writev(2) システムコールで変更されます。
- st_ctim
- ファイルステータスが最後に変更された時刻 (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_birthtim
- inode が作成されたときの時刻。
次の時間に関連するマクロは、互換性のために定義されています:
#define st_atime st_atim.tv_sec #define st_mtime st_mtim.tv_sec #define st_ctime st_ctim.tv_sec #ifndef _POSIX_SOURCE #define st_birthtime st_birthtim.tv_sec #endif #ifndef _POSIX_SOURCE #define st_atimespec st_atim #define st_mtimespec st_mtim #define st_ctimespec st_ctim #define st_birthtimespec st_birthtim #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_IRWXU 0000700 /* 所有者の RWX マスク */ #define S_IRUSR 0000400 /* 読み込み権限の所有者 */ #define S_IWUSR 0000200 /* 書み込み権限の所有者 */ #define S_IXUSR 0000100 /* 実行 / 検索権限の所有者 */ #define S_IRWXG 0000070 /* グループの RWX マスク */ #define S_IRGRP 0000040 /* 読み込みパーミッション, グループ */ #define S_IWGRP 0000020 /* 書き込みパーミッション, グループ */ #define S_IXGRP 0000010 /* 実行/検索パーミッション, グループ */ #define S_IRWXO 0000007 /* 他者の RWX マスク */ #define S_IROTH 0000004 /* 読み込みパーミッション, 他者 */ #define S_IWOTH 0000002 /* 書き込みパーミッション, 他者 */ #define S_IXOTH 0000001 /* 実行/検索パーミッション, 他者 */
アクセスモードのリストについては、 < 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 に評価します。
戻り値
Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the error.互換性
以前のバージョンのシステムでは、 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 で指されている構造体で正しく表現できません。
lstat() によって返されたエラーに加えて fstatat() は、次の場合に失敗します:
- [ EBADF]
- path 引数が、絶対パスを指定していません、そして fd 引数は、 AT_FDCWD でもなく検索のためにオープンされた有効なファイル記述子でもありません。
- [ EINVAL]
- flag 引数の値は、有効ではありません。
- [ ENOTDIR]
- path 引数が、絶対パスではありません、そして fd が、 AT_FDCWD でもなくディレクトリに関連しているファイル記述子でもありません。
規格
stat() と fstat() システムコールは、 IEEE Std 1003.1-1990 (“POSIX.1”) に適合するはずです。 fstatat() システムコールは、The Open Group Extended API Set 2 仕様に従っています。歴史
stat() と fstat() システムコールは、 Version 7 AT&T UNIX で登場しました。 lstat() システムコールは、 4.2BSD で登場しました。 fstatat() システムコールは、 FreeBSD 8.0 で登場しました。バグ
fstat() をソケットに適用すると、ブロックサイズフィールド、および固有デバイスと inode 番号以外に 0 の入ったバッファが戻されます。June 2, 2012 | FreeBSD |