Provided by: manpages-ja-dev_0.5.0.0.20131015+dfsg-2_all
名前
stat, fstat, lstat - ファイルの状態を取得する
書式
#include <sys/types.h> #include <sys/stat.h> #include <unistd.h> int stat(const char *path, struct stat *buf); int fstat(int fd, struct stat *buf); int lstat(const char *path, struct stat *buf); glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照): lstat(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* glibc 2.10 以降: */ _POSIX_C_SOURCE >= 200112L
説明
これらの関数はファイルについての情報を返す。 ファイルそのものに対するアクセス許可は必要と しないが、 —stat() と lstat() の場合には — そのファイルへ至る path を構成する全てのディレ クトリに対する 実行 (検索) 許可が必要である。 stat() は path で指定されたファイルの状態を取得して buf へ格納する。 lstat() は stat() と同じであるが、 path がシンボリックリンクの場合、リンクが参照している ファイルではなく、 リンク自身の状態を取得する点が異なる。 fstat() は stat() と同じだが、 状態を取得するファイルをファイル・ディスクリプタ fd で指 定する。 これらのシステムコールはいずれも、結果を stat 構造体に入れて返す。 stat 構造体には以下の フィールドが含まれている: struct stat { dev_t st_dev; /* ファイルがあるデバイスの ID */ ino_t st_ino; /* inode 番号 */ mode_t st_mode; /* アクセス保護 */ nlink_t st_nlink; /* ハードリンクの数 */ uid_t st_uid; /* 所有者のユーザ ID */ gid_t st_gid; /* 所有者のグループ ID */ dev_t st_rdev; /* デバイス ID (特殊ファイルの場合) */ off_t st_size; /* 全体のサイズ (バイト単位) */ blksize_t st_blksize; /* ファイルシステム I/O での ブロックサイズ */ blkcnt_t st_blocks; /* 割り当てられた 512B のブロック数 */ time_t st_atime; /* 最終アクセス時刻 */ time_t st_mtime; /* 最終修正時刻 */ time_t st_ctime; /* 最終状態変更時刻 */ }; st_dev フィールドは、このファイルが存在するデバイスを示す (マクロ major(3), minor(3) は、このフィールドのデバイス ID を分解するのに役立つだろう)。 st_rdev フィールドは、このファイル (inode) が表すデバイスを示す。 st_size フィールドは、(通常のファイルかシンボリックリンクの場合に) ファイルの大きさをバイ ト単位で示す。 シンボリックリンクの大きさは、 シンボリックリンクに含まれている パス名の長 さ (終端の NULL バイトは含まない) である。 st_blocks フィールドは、ファイルの大きさを 512 バイトのブロックサイズ単位で示す フィールド は、ファイルに割り当てされたブロック数を 512 バイト単位で示す。 (ファイルに穴があるような 場合、この値は st_size/512 より小さくなることもある)。 st_blksize フィールドは、効率的にファイルシステム I/O ができる「好ましい」 ブロックサイズ を示す (もっと小さい単位でファイルに書き込みを行うと、 読み出し--修正--再書き込みといった 非効率な動作になってしまうかもしれない)。 全ての Linux のファイルシステムが全ての時間フィールドを 実装しているわけではない。 ファイ ルやディレクトリのアクセスが st_atime フィールドを更新しないようなかたちでマウントできる ファイルシステムもある。 (mount(8) の noatime, nodiratime, relatime や mount(2) の関連す る情報を参照)。 また、ファイルが O_NOATIME 付きでオープンされている場合には st_atime は更 新されない。 open(2) 参照。 st_atime フィールドはファイルアクセスがあった場合に変更される (例えば、 execve(2), mknod(2), pipe(2), utime(2) を使用した場合や read(2) で 1 バイト以上読み込んだ場合な ど)。 mmap(2) などの他のルーチンでは、 st_atime は更新されることもあれば、そうでない場合 もある。 st_mtime フィールドは、ファイルが修正された場合に変更される (例えば、 mknod(2), truncate(2), utime(2) を使用した場合や write(2) で 1 バイト以上書き込みをした場合など)。 さらに、ディレクトリの st_mtime は、そのディレクトリで ファイルが作成されたり削除されたり すると変更される。 st_mtime フィールドは 所有者やグループやハード・リンク数やモードの変更 では変更 されない。 st_ctime フィールドは書き込みや inode 情報 (所有者、グループ、リンク数、モードなど) の 設 定によって変更される。 以下の POSIX マクロは、 st_mode フィールド で使用されるファイル種別のチェックのために定義 されている : S_ISREG(m) 通常のファイルか? S_ISDIR(m) ディレクトリか? S_ISCHR(m) キャラクター・デバイスか? S_ISBLK(m) ブロック・デバイスか? S_ISFIFO(m) FIFO (名前付きパイプ) か? S_ISLNK(m) シンボリックリンクか? (POSIX.1-1996 にはない) S_ISSOCK(m) ソケットか? (POSIX.1-1996 にはない) 以下のフラグが st_mode フィールド用に定義されている: S_IFMT 0170000 ファイル種別を示すビット領域を表すビットマスク S_IFSOCK 0140000 ソケット S_IFLNK 0120000 シンボリックリンク S_IFREG 0100000 通常のファイル S_IFBLK 0060000 ブロック・デバイス S_IFDIR 0040000 ディレクトリ S_IFCHR 0020000 キャラクター・デバイス S_IFIFO 0010000 FIFO S_ISUID 0004000 set-user-ID bit S_ISGID 0002000 set-group-ID bit (下記参照) S_ISVTX 0001000 スティッキー・ビット (下記参照) S_IRWXU 00700 ファイル所有者のアクセス許可用のビットマスク S_IRUSR 00400 所有者の読み込み許可 S_IWUSR 00200 所有者の書き込み許可 S_IXUSR 00100 所有者の実行許可 S_IRWXG 00070 グループのアクセス許可用のビットマスク S_IRGRP 00040 グループの読み込み許可 S_IWGRP 00020 グループの書き込み許可 S_IXGRP 00010 グループの実行許可 S_IRWXO 00007 他人 (others) のアクセス許可用のビットマスク S_IROTH 00004 他人の読み込み許可 S_IWOTH 00002 他人の書き込み許可 S_IXOTH 00001 他人の実行許可 set-group-ID bit (S_ISGID) にはいくつかの特殊な使用法がある: ディレクトリに設定した場合に は、そのディレクトリが BSD 方式で使用される ことを示す。つまり、そのディレクトリに作成され たファイルのグループID は 作成したプロセスの実効 (effective) グループID ではなく、ディレク トリの グループID を継承する。また、そのディレクトリに作成されたディレクトリにも S_ISGID ビットが設定される。グループ実行ビット (S_IXGRP) が設定されていないファイルに設定された場 合は、 set-group-ID ビットはファイル/レコードの 強制的な (mandatory) ロックを表す。 ディレクトリにスティッキービット (S_ISVTX) が設定された場合は、 そのディレクトリのファイル の名前を変更したり、削除したりできるのは、 そのファイルの所有者か、そのディレクトリの所有 者か、特権プロセス だけとなる。
返り値
成功した場合、0 が返される。 失敗した場合、 -1 が返され、 errno に適切な値がセットされる。
エラー
EACCES path が所属するディレクトリとその上位のディレクトリのいずれかに 対する検索許可がな かった (path_resolution(7) も参照のこと)。 EBADF fd が不正である。 EFAULT アドレスが間違っている。 ELOOP パスを辿る際に解決すべきシンボリックリンクが多過ぎた。 ENAMETOOLONG path が長過ぎる。 ENOENT path の構成要素が存在しないか、 path が空文字列である。 ENOMEM カーネルのメモリが足りない。 ENOTDIR path の前半部分 (prefix) の構成要素がディレクトリではない。 EOVERFLOW path または fd が、ファイルサイズ、inode 番号、ブロック数が それぞれ off_t 型、 ino_t 型、 blkcnt_t 型で表現できないファイルを 参照している。このエラーが起こるの は、例えば、32 ビットプラットフォーム上で -D_FILE_OFFSET_BITS=64 を指定せずにコンパ イルされたアプリケーションが、 ファイルサイズが (1<<31)-1 バイトを超えるファイルに 対して stat() を呼び出した場合である。
準拠
これらのシステムコールは SVr4, 4.3BSD, POSIX.1-2001 に準拠している。 stat() と fstat() コールは SVr4, SVID, POSIX, X/OPEN, 4.3BSD に準拠している。 lstat() コールは 4.3BSD と SVr4 に準拠している。 POSIX.1-2001 では、シンボリックリンクに対する lstat() で 有効な情報を返すように求められて いたのは、 stat 構造体の st_size と st_mode のファイル種別要素だけであった。 POSIX.1-2008 では規定が厳しくなり、 lstat() は st_mode の アクセス許可ビット以外の全てのフィールドに有 効な情報を返すことが 求められるようになっている。 st_blocks と st_blksize フィールドの使用はあまり移植性がない (これらのフィールドは BSD に よって導入された。 システムごとに解釈が 異なっており、 NFS マウントの場合には同じシステム でも異なる可能性がある)。 <sys/stat.h> から blkcnt_t の blksize_t 型定義を 読み込みたい場 合は、(どのヘッダファイルをインクルードするよりも前に) _XOPEN_SOURCE を 500 以上の値で定義 すること。 POSIX.1-1990 には S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX 定数に関する 記述はなかったが、代わりに S_ISDIR() のようなマクロを使用するように 要求していた。 S_IF* 定数は POSIX.1-2001 以降には存在する。 マクロ S_ISLNK() と S_ISSOCK() は POSIX.1-1996 にはないが、 POSIX.1-2001 には両方とも存在 する。 前者は SVID 4 に、後者は SUSv2 に 由来している。 UNIX V7 (とその後のシステム) は S_IREAD, S_IWRITE, S_IEXEC を持っており、 POSIX はその同義 語として S_IRUSR, S_IWUSR, S_IXUSR を規定している。 他のシステム 各種システムで使用されていた(いる)値: 16進 名前 ls 8進数 説明 f000 S_IFMT 170000 ファイル種別フィールドのビットマスク 0000 000000 SCO では 使用不能 inode; BSD では不明な ファイル種別; SVID-v2 と XPG2 では 0 と 0100000 の両方が通常のファイル 1000 S_IFIFO p| 010000 FIFO (名前付きパイプ) 2000 S_IFCHR c 020000 キャラクタ特殊ファイル (V7) 3000 S_IFMPC 030000 多重化されたキャラクタ特殊ファイル (V7) 4000 S_IFDIR d/ 040000 ディレクトリ (V7) 5000 S_IFNAM 050000 XENIX の二つの副型を持つ名前付きの特殊 ファイル 副型は st_rdev の値 1, 2 で区 別される 0001 S_INSEM s 000001 XENIX の IFNAM セマフォ副型 0002 S_INSHD m 000002 XENIX の IFNAM 共有データ副型 6000 S_IFBLK b 060000 ブロック特殊ファイル (V7) 7000 S_IFMPB 070000 多重化されたブロック特殊ファイル (V7) 8000 S_IFREG - 100000 通常ファイル (V7) 9000 S_IFCMP 110000 VxFS 圧縮ファイル 9000 S_IFNWK n 110000 ネットワーク特殊ファイル (HP-UX) a000 S_IFLNK l@ 120000 シンボリックリンク (BSD) b000 S_IFSHAD 130000 Solaris の ACL 用の隠し inode (ユーザ空 間からは見えない) c000 S_IFSOCK s= 140000 ソケット (BSD; VxFS の "S_IFSOC") d000 S_IFDOOR D> 150000 Solaris の door ファイル e000 S_IFWHT w% 160000 BSD の空白ファイル (inode を使用しない) 0200 S_ISVTX 001000 スティッキービット: 使用後もスワップに 残す (V7) 予約 (SVID-v2) ディレクトリ以外: ファイルをキャッシュ しない (SunOS) ディレクトリの場合: 削除制限フラグ (SVID-v4.2) 0400 S_ISGID 002000 実行時の set-group-ID (V7) ディレクトリの場合: GID の伝搬に BSD 方 式を使用する 0400 S_ENFMT 002000 System V ファイルロックを強制する (S_ISGID と共有) 0800 S_ISUID 004000 実行時の set-user-ID (V7) 0800 S_CDF 004000 ディレクトリがコンテキスト依存ファイル (HP-UX) スティッキー コマンドは Version 32V AT&T UNIX で登場した。
注意
カーネル 2.5.48 以降では、 stat 構造体は 3 つのファイルのタイムスタンプ 関連のフィールドで ナノ秒単位の精度に対応している。 glibc では、機能検査 マクロ _BSD_SOURCE か _SVID_SOURCE が定義された場合に、各フィールドの ナノ秒の情報を st_atim.tv_nsec という形式の名前で公開す る。 これらのフィールドは POSIX.1-2008 で規定されており、 バージョン 2.12 以降の glibc で は、 _POSIX_C_SOURCE が 200809L 以上の値で定義されるか、 _XOPEN_SOURCE が 700 以上の値で定 義された場合に、 これらのフィールドが公開される。 上記のマクロのいずれも定義されていない場 合、ナノ秒の値は st_atimensec という形式の名前で公開される。 秒より細かいタイムスタンプを サポートしていないファイルシステムでは、 ナノ秒のフィールドは 0 に設定される。 Linux では、 lstat() は一般には自動マウント動作 (automounter action) の きっかけとならない が、 stat() はきっかけとなる (fstatat(2) を参照)。 /proc ディレクトリ以下にあるファイルのほとんどでは、 stat() を呼び出した際に、 st_size フィールドにファイルサイズが返されない。 代わりに st_size フィールドには 0 が返される。 背後のカーネル・インタフェース 時間の経過とともに、 stat 構造体のサイズが大きくなり、この影響で stat() には 3つのバー ジョンが存在する: sys_stat() (スロットは __NR_oldstat)、 sys_newstat() (スロットは __NR_stat)、 sys_stat64() (カーネル 2.4 で導入; スロットは __NR_stat64). glibc の stat() ラッパー関数はこれらの詳細をアプリケーションから隠蔽してくれる。 具体的には、カーネルが提 供しているシステムコールのうち最新のバージョンを 起動し、古いバイナリの場合には必要に応じ て返された情報を再構成 (repack) する。 fstat() と lstat() についても同様である。
例
以下のプログラムは stat() を呼び出し、返ってきた stat 構造体のフィールドのいくつかを表示 する。 #include <sys/types.h> #include <sys/stat.h> #include <time.h> #include <stdio.h> #include <stdlib.h> int main(int argc, char *argv[]) { struct stat sb; if (argc != 2) { fprintf(stderr, "Usage: %s <pathname>\n", argv[0]); exit(EXIT_FAILURE); } if (stat(argv[1], &sb) == -1) { perror("stat"); exit(EXIT_FAILURE); } printf("File type: "); switch (sb.st_mode & S_IFMT) { case S_IFBLK: printf("block device\n"); break; case S_IFCHR: printf("character device\n"); break; case S_IFDIR: printf("directory\n"); break; case S_IFIFO: printf("FIFO/pipe\n"); break; case S_IFLNK: printf("symlink\n"); break; case S_IFREG: printf("regular file\n"); break; case S_IFSOCK: printf("socket\n"); break; default: printf("unknown?\n"); break; } printf("I-node number: %ld\n", (long) sb.st_ino); printf("Mode: %lo (octal)\n", (unsigned long) sb.st_mode); printf("Link count: %ld\n", (long) sb.st_nlink); printf("Ownership: UID=%ld GID=%ld\n", (long) sb.st_uid, (long) sb.st_gid); printf("Preferred I/O block size: %ld bytes\n", (long) sb.st_blksize); printf("File size: %lld bytes\n", (long long) sb.st_size); printf("Blocks allocated: %lld\n", (long long) sb.st_blocks); printf("Last status change: %s", ctime(&sb.st_ctime)); printf("Last file access: %s", ctime(&sb.st_atime)); printf("Last file modification: %s", ctime(&sb.st_mtime)); exit(EXIT_SUCCESS); }
関連項目
access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capabilities(7), symlink(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.54 の一部 である。プロジェクト の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。