.\" t
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
.\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified by Michael Haardt <michael@moria.de>
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org>
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk>
.\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
.\" Modified 1999-07-06 by aeb & Albert Cahalan
.\" Modified 2000-01-07 by aeb
.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
.\" 2007-06-08 mtk: Added example program
.\" 2007-07-05 mtk: Added details on underlying system call interfaces
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH STAT 2 2012\-05\-07 Linux "Linux Programmer's Manual"
.SH 名前
stat, fstat, lstat \- ファイルの状態を取得する
.SH 書式
\fB#include <sys/types.h>\fP
.br
\fB#include <sys/stat.h>\fP
.br
\fB#include <unistd.h>\fP
.sp
\fBint stat(const char *\fP\fIpath\fP\fB, struct stat *\fP\fIbuf\fP\fB);\fP
.br
\fBint fstat(int \fP\fIfd\fP\fB, struct stat *\fP\fIbuf\fP\fB);\fP
.br
\fBint lstat(const char *\fP\fIpath\fP\fB, struct stat *\fP\fIbuf\fP\fB);\fP
.sp
.in -4n
glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
.in
.ad l
.PD 0
.sp
\fBlstat\fP():
.RS 4
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
.br
|| /* glibc 2.10 以降: */ _POSIX_C_SOURCE\ >=\ 200112L
.RE
.PD
.ad
.SH 説明
.PP
これらの関数はファイルについての情報を返す。
ファイルそのものに対するアクセス許可は必要としないが、
\(em\fBstat\fP() と \fBlstat\fP()  の場合には \(em
そのファイルへ至る \fIpath\fP を構成する全てのディレクトリに対する
実行 (検索) 許可が必要である。
.PP
\fBstat\fP()  は \fIpath\fP で指定されたファイルの状態を取得して \fIbuf\fP へ格納する。

\fBlstat\fP()  は \fBstat\fP()  と同じであるが、 \fIpath\fP がシンボリックリンクの場合、リンクが参照しているファイルではなく、
リンク自身の状態を取得する点が異なる。

\fBfstat\fP()  は \fBstat\fP()  と同じだが、 状態を取得するファイルをファイル・ディスクリプタ \fIfd\fP で指定する。
.PP
これらのシステムコールはいずれも、結果を \fIstat\fP 構造体に入れて返す。 \fIstat\fP 構造体には以下のフィールドが含まれている:
.PP
.in +4n
.nf
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;   /* 最終状態変更時刻 */
};
.fi
.in
.PP
\fIst_dev\fP フィールドは、このファイルが存在するデバイスを示す (マクロ \fBmajor\fP(3), \fBminor\fP(3)
は、このフィールドのデバイス ID を分解するのに役立つだろう)。

\fIst_rdev\fP フィールドは、このファイル (inode) が表すデバイスを示す。

\fIst_size\fP フィールドは、(通常のファイルかシンボリックリンクの場合に)
ファイルの大きさをバイト単位で示す。 シンボリックリンクの大きさは、
シンボリックリンクに含まれている パス名の長さ (終端の NULL バイトは含まない)
である。

\fIst_blocks\fP フィールドは、ファイルの大きさを 512 バイトのブロックサイズ単位で示す フィールドは、ファイルに割り当てされたブロック数を
512 バイト単位で示す。 (ファイルに穴があるような場合、この値は \fIst_size\fP/512 より小さくなることもある)。

\fIst_blksize\fP フィールドは、効率的にファイルシステム I/O ができる「好ましい」 ブロックサイズを示す
(もっと小さい単位でファイルに書き込みを行うと、 読み出し\-\-修正\-\-再書き込みといった非効率な動作になってしまうかもしれない)。
.PP
全ての Linux のファイルシステムが全ての時間フィールドを 実装しているわけではない。 ファイルやディレクトリのアクセスが \fIst_atime\fP
フィールドを更新しないようなかたちでマウントできるファイルシステムもある。 (\fBmount\fP(8)  の \fInoatime\fP,
\fInodiratime\fP, \fIrelatime\fP や \fBmount\fP(2)  の関連する情報を参照)。 また、ファイルが \fBO_NOATIME\fP
付きでオープンされている場合には \fIst_atime\fP は更新されない。 \fBopen\fP(2)  参照。

\fIst_atime\fP フィールドはファイルアクセスがあった場合に変更される (例えば、 \fBexecve\fP(2), \fBmknod\fP(2),
\fBpipe\fP(2), \fButime\fP(2)  を使用した場合や \fBread\fP(2)  で 1 バイト以上読み込んだ場合など)。
\fBmmap\fP(2)  などの他のルーチンでは、 \fIst_atime\fP は更新されることもあれば、そうでない場合もある。

\fIst_mtime\fP フィールドは、ファイルが修正された場合に変更される (例えば、 \fBmknod\fP(2), \fBtruncate\fP(2),
\fButime\fP(2)  を使用した場合や \fBwrite\fP(2)  で 1 バイト以上書き込みをした場合など)。 さらに、ディレクトリの
\fIst_mtime\fP は、そのディレクトリで ファイルが作成されたり削除されたりすると変更される。 \fIst_mtime\fP フィールドは
所有者やグループやハード・リンク数やモードの変更では変更 \fIされない。\fP

\fIst_ctime\fP フィールドは書き込みや inode 情報 (所有者、グループ、リンク数、モードなど) の 設定によって変更される。
.PP
以下の POSIX マクロは、 \fIst_mode\fP フィールド で使用されるファイル種別のチェックのために定義されている :
.RS 4
.TP  1.2i
\fBS_ISREG\fP(m)
通常のファイルか?
.TP 
\fBS_ISDIR\fP(m)
ディレクトリか?
.TP 
\fBS_ISCHR\fP(m)
キャラクター・デバイスか?
.TP 
\fBS_ISBLK\fP(m)
ブロック・デバイスか?
.TP 
\fBS_ISFIFO\fP(m)
FIFO (名前付きパイプ) か?
.TP 
\fBS_ISLNK\fP(m)
シンボリックリンクか? (POSIX.1\-1996 にはない)
.TP 
\fBS_ISSOCK\fP(m)
ソケットか? (POSIX.1\-1996 にはない)
.RE
.PP
以下のフラグが \fIst_mode\fP フィールド用に定義されている:
.in +4n
.TS
lB l l.
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	他人の実行許可
.TE
.in
.P
set\-group\-ID bit (\fBS_ISGID\fP)  にはいくつかの特殊な使用法がある: ディレクトリに設定した場合には、そのディレクトリが
BSD 方式で使用される ことを示す。つまり、そのディレクトリに作成されたファイルのグループID は 作成したプロセスの実効 (effective)
グループID ではなく、ディレクトリの グループID を継承する。また、そのディレクトリに作成されたディレクトリにも \fBS_ISGID\fP
ビットが設定される。グループ実行ビット (\fBS_IXGRP\fP)  が設定されていないファイルに設定された場合は、 set\-group\-ID
ビットはファイル/レコードの 強制的な (mandatory) ロックを表す。
.P
ディレクトリにスティッキービット (S_ISVTX) が設定された場合は、 そのディレクトリのファイルの名前を変更したり、削除したりできるのは、
そのファイルの所有者か、そのディレクトリの所有者か、特権プロセス だけとなる。
.SH 返り値
成功した場合、0 が返される。 失敗した場合、 \-1 が返され、 \fIerrno\fP に適切な値がセットされる。
.SH エラー
.TP 
\fBEACCES\fP
\fIpath\fP が所属するディレクトリとその上位のディレクトリのいずれかに 対する検索許可がなかった (\fBpath_resolution\fP(7)
も参照のこと)。
.TP 
\fBEBADF\fP
\fIfd\fP が不正である。
.TP 
\fBEFAULT\fP
アドレスが間違っている。
.TP 
\fBELOOP\fP
パスを辿る際に解決すべきシンボリックリンクが多過ぎた。
.TP 
\fBENAMETOOLONG\fP
\fIpath\fP が長過ぎる。
.TP 
\fBENOENT\fP
\fIpath\fP の構成要素が存在しないか、 \fIpath\fP が空文字列である。
.TP 
\fBENOMEM\fP
カーネルのメモリが足りない。
.TP 
\fBENOTDIR\fP
\fIpath\fP の前半部分 (prefix) の構成要素がディレクトリではない。
.TP 
\fBEOVERFLOW\fP
(\fBstat\fP()) \fIpath\fP が、ファイルサイズを \fIoff_t\fP 型で表現できないファイルを
参照している。このエラーが起こるのは、32 ビットプラットフォーム上で
\fI\-D_FILE_OFFSET_BITS=64\fP を指定せずにコンパイルされたアプリケーションが、
ファイルサイズが \fI(1<<31)\-1\fP ビットを超えるファイルに対して \fBstat\fP()
を呼び出した場合である。
.SH 準拠
.\" SVr4 documents additional
.\" .BR fstat ()
.\" error conditions EINTR, ENOLINK, and EOVERFLOW.  SVr4
.\" documents additional
.\" .BR stat ()
.\" and
.\" .BR lstat ()
.\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
これらのシステムコールは SVr4, 4.3BSD, POSIX.1\-2001 に準拠している。 \fBstat\fP()  と \fBfstat\fP()
コールは SVr4, SVID, POSIX, X/OPEN, 4.3BSD に準拠している。 \fBlstat\fP()  コールは 4.3BSD と
SVr4 に準拠している。

POSIX.1\-2001 では、シンボリックリンクに対する \fBlstat\fP() で
有効な情報を返すように求められていたのは、 \fIstat\fP 構造体の \fIst_size\fP
と \fIst_mode\fP のファイル種別要素だけであった。
POSIX.1\-2008 では規定が厳しくなり、 \fBlstat\fP() は \fIst_mode\fP の
アクセス許可ビット以外の全てのフィールドに有効な情報を返すことが
求められるようになっている。

\fIst_blocks\fP と \fIst_blksize\fP フィールドの使用はあまり移植性がない
(これらのフィールドは BSD によって導入された。 システムごとに解釈が
異なっており、 NFS マウントの場合には同じシステムでも異なる可能性がある)。
\fI<sys/stat.h>\fP から \fIblkcnt_t\fP の \fIblksize_t\fP 型定義を
読み込みたい場合は、(\fIどの\fPヘッダファイルをインクルードするよりも前に)
\fB_XOPEN_SOURCE\fP を 500 以上の値で定義すること。
.LP
POSIX.1\-1990 には \fBS_IFMT\fP, \fBS_IFSOCK\fP, \fBS_IFLNK\fP, \fBS_IFREG\fP,
\fBS_IFBLK\fP, \fBS_IFDIR\fP, \fBS_IFCHR\fP, \fBS_IFIFO\fP, \fBS_ISVTX\fP 定数に関する
記述はなかったが、代わりに \fBS_ISDIR\fP() のようなマクロを使用するように
要求していた。 \fBS_IF*\fP 定数は POSIX.1\-2011 以降には存在する。

マクロ \fBS_ISLNK\fP() と \fBS_ISSOCK\fP() は POSIX.1\-1996 にはないが、
POSIX.1\-2001 には両方とも存在する。 前者は SVID 4 に、後者は SUSv2 に
由来している。
.LP
UNIX V7 (とその後のシステム) は \fBS_IREAD\fP, \fBS_IWRITE\fP, \fBS_IEXEC\fP を持っており、
POSIX はその同義語として \fBS_IRUSR\fP, \fBS_IWUSR\fP, \fBS_IXUSR\fP を規定している。
.SS 他のシステム
各種システムで使用されていた(いる)値:
.ad l
.TS
l l l l l.
16進	名前	ls	8進数	説明
f000	S_IFMT		170000	ファイル種別フィールドのビットマスク
0000			000000	T{
SCO では 使用不能 inode; BSD では不明なファイル種別;
SVID\-v2 と XPG2 では 0 と 0100000 の両方が通常のファイル
T}
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	T{
XENIX の二つの副型を持つ名前付きの特殊ファイル
副型は \fIst_rdev\fP の値 1, 2 で区別される
T}
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	T{
Solaris の ACL 用の隠し inode (ユーザ空間からは見えない)
T}
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	T{
スティッキービット: 使用後もスワップに残す (V7)
.br
予約 (SVID\-v2)
.br
ディレクトリ以外: ファイルをキャッシュしない (SunOS)
.br
ディレクトリの場合: 削除制限フラグ (SVID\-v4.2)
T}
0400	S_ISGID		002000	T{
実行時の set\-group\-ID (V7)
.br
ディレクトリの場合: GID の伝搬に BSD 方式を使用する
T}
0400	S_ENFMT		002000	T{
System V ファイルロックを強制する (S_ISGID と共有)
T}
0800	S_ISUID		004000	実行時の set\-user\-ID (V7)
0800	S_CDF		004000	T{
ディレクトリがコンテキスト依存ファイル (HP\-UX)
T}
.TE
.ad

スティッキー コマンドは Version 32V AT&T UNIX で登場した。
.SH 注意
.\" As at kernel 2.6.25, XFS and JFS support nanosecond timestamps,
.\" but ext2, ext3, and Reiserfs do not.
カーネル 2.5.48 以降では、 \fIstat\fP 構造体は 3 つのファイルのタイムスタンプ
関連のフィールドでナノ秒単位の精度に対応している。 glibc では、機能検査
マクロ \fB_BSD_SOURCE\fP か \fB_SVID_SOURCE\fP が定義された場合に、各フィールドの
ナノ秒の情報を \fIst_atim.tv_nsec\fP という形式の名前で公開する。
これらのフィールドは POSIX.1\-2008 で規定されており、
バージョン 2.12 以降の glibc では、
\fB_POSIX_C_SOURCE\fP が 200809L 以上の値で定義されるか、
\fB_XOPEN_SOURCE\fP が 700 以上の値で定義された場合に、
これらのフィールドが公開される。
上記のマクロのいずれも定義されていない場合、ナノ秒の値は
\fIst_atimensec\fP という形式の名前で公開される。
秒より細かいタイムスタンプをサポートしていないファイルシステムでは、
ナノ秒のフィールドは 0 に設定される。

Linux では、 \fBlstat\fP() は一般には自動マウント動作 (automounter action) の
きっかけとならないが、 \fBstat\fP() はきっかけとなる (\fBfstatat\fP(2) を参照)。

\fI/proc\fP ディレクトリ以下にあるファイルのほとんどでは、 \fBstat\fP()  を呼び出した際に、 \fIst_size\fP
フィールドにファイルサイズが返されない。 代わりに \fIst_size\fP フィールドには 0 が返される。
.SS 背後のカーネル・インタフェース
.\"
.\" A note from Andries Brouwer, July 2007
.\"
.\" > Is the story not rather more complicated for some calls like
.\" > stat(2)?
.\"
.\" Yes and no, mostly no. See /usr/include/sys/stat.h .
.\"
.\" The idea is here not so much that syscalls change, but that
.\" the definitions of struct stat and of the types dev_t and mode_t change.
.\" This means that libc (even if it does not call the kernel
.\" but only calls some internal function) must know what the
.\" format of dev_t or of struct stat is.
.\" The communication between the application and libc goes via
.\" the include file <sys/stat.h> that defines a _STAT_VER and
.\" _MKNOD_VER describing the layout of the data that user space
.\" uses. Each (almost each) occurrence of stat() is replaced by
.\" an occurrence of xstat() where the first parameter of xstat()
.\" is this version number _STAT_VER.
.\"
.\" Now, also the definitions used by the kernel change.
.\" But glibc copes with this in the standard way, and the
.\" struct stat as returned by the kernel is repacked into
.\" the struct stat as expected by the application.
.\" Thus, _STAT_VER and this setup cater for the application-libc
.\" interface, rather than the libc-kernel interface.
.\"
.\" (Note that the details depend on gcc being used as c compiler.)
時間の経過とともに、 \fIstat\fP 構造体のサイズが大きくなり、この影響で \fBstat\fP()  には 3つのバージョンが存在する:
\fIsys_stat\fP()  (スロットは \fI__NR_oldstat\fP)、 \fIsys_newstat\fP()  (スロットは
\fI__NR_stat\fP)、 \fIsys_stat64\fP()  (カーネル 2.4 で導入; スロットは \fI__NR_stat64\fP).  glibc
の \fBstat\fP()  ラッパー関数はこれらの詳細をアプリケーションから隠蔽してくれる。
具体的には、カーネルが提供しているシステムコールのうち最新のバージョンを 起動し、古いバイナリの場合には必要に応じて返された情報を再構成
(repack) する。 \fBfstat\fP()  と \fBlstat\fP()  についても同様である。
.SH 例
以下のプログラムは \fBstat\fP()  を呼び出し、返ってきた \fIstat\fP 構造体のフィールドのいくつかを表示する。
.nf

#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>\en", 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\en");            break;
    case S_IFCHR:  printf("character device\en");        break;
    case S_IFDIR:  printf("directory\en");               break;
    case S_IFIFO:  printf("FIFO/pipe\en");               break;
    case S_IFLNK:  printf("symlink\en");                 break;
    case S_IFREG:  printf("regular file\en");            break;
    case S_IFSOCK: printf("socket\en");                  break;
    default:       printf("unknown?\en");                break;
    }

    printf("I\-node number:            %ld\en", (long) sb.st_ino);

    printf("Mode:                     %lo (octal)\en",
            (unsigned long) sb.st_mode);

    printf("Link count:               %ld\en", (long) sb.st_nlink);
    printf("Ownership:                UID=%ld   GID=%ld\en",
            (long) sb.st_uid, (long) sb.st_gid);

    printf("Preferred I/O block size: %ld bytes\en",
            (long) sb.st_blksize);
    printf("File size:                %lld bytes\en",
            (long long) sb.st_size);
    printf("Blocks allocated:         %lld\en",
            (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);
}
.fi
.SH 関連項目
\fBaccess\fP(2), \fBchmod\fP(2), \fBchown\fP(2), \fBfstatat\fP(2), \fBreadlink\fP(2),
\fButime\fP(2), \fBcapabilities\fP(7), \fBsymlink\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.41 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。