'\" t
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 2006 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.
.\"
.\" Japanese Version Copyright (c) 2006 Yuichi SATO
.\"     and Copyright (c) 2007-2008 Akihiro MOTOKI
.\" Translated 2006-07-05 by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v2.29
.\" Updated 2006-07-20 by Yuichi SATO, LDP v2.36
.\" Updated 2007-06-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.55
.\" Updated 2008-08-10, Akihiro MOTOKI, LDP v3.05
.\" Updated 2008-09-19, Akihiro MOTOKI, LDP v3.08
.\"
.TH INOTIFY 7 2008-11-18 "Linux" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O inotify \- monitoring file system events
inotify \- ファイルシステムイベントを監視する
.\"O .SH DESCRIPTION
.SH 説明
.\"O The
.\"O .I inotify
.\"O API provides a mechanism for monitoring file system events.
.I inotify
API はファイルシステムイベントを監視するための機構を提供する。
.\"O Inotify can be used to monitor individual files,
.\"O or to monitor directories.
inotify は個々のファイルやディレクトリを監視するのに使える。
.\"O When a directory is monitored, inotify will return events
.\"O for the directory itself, and for files inside the directory.
ディレクトリを監視する場合、inotify はディレクトリ自身と
ディレクトリ内のファイルのイベントを返す。

.\"O The following system calls are used with this API:
.\"O .BR inotify_init (2)
.\"O (or
.\"O .BR inotify_init1 (2)),
.\"O .BR inotify_add_watch (2),
.\"O .BR inotify_rm_watch (2),
.\"O .BR read (2),
.\"O and
.\"O .BR close (2).
以下のシステムコールがこの API と共に使用される:
.BR inotify_init (2)
(や
.BR inotify_init1 (2)),
.BR inotify_add_watch (2),
.BR inotify_rm_watch (2),
.BR read (2),
.BR close (2).

.\"O .BR inotify_init (2)
.\"O creates an inotify instance and returns a file descriptor
.\"O referring to the inotify instance.
.\"O The more recent
.\"O .BR inotify_init1 (2)
.\"O is like
.\"O .BR inotify_init (2),
.\"O but provides some extra functionality.
.BR inotify_init (2)
は inotify インスタンスを作成し、inotify インスタンスを参照する
ファイルディスクリプタを返す。
もっと新しい
.BR inotify_init1 (2)
も
.BR inotify_init (2)
と同様だが、いくつかの追加の機能が提供されている。

.\"O .BR inotify_add_watch (2)
.\"O manipulates the "watch list" associated with an inotify instance.
.BR inotify_add_watch (2)
は inotify インスタンスに関連づけられた「監視対象 (watch) リスト」を操作する。
.\"O Each item ("watch") in the watch list specifies the pathname of
.\"O a file or directory,
.\"O along with some set of events that the kernel should monitor for the
.\"O file referred to by that pathname.
監視対象リストの各アイテム ("watch") は、
ファイルまたはディレクトリのパス名と、
そのパス名で参照されるファイルに対して
カーネルが監視する複数のイベントの集合を指定する。
.\"O .BR inotify_add_watch (2)
.\"O either creates a new watch item, or modifies an existing watch.
.BR inotify_add_watch (2)
は新しい監視アイテムの作成や既存の監視対象の変更ができる。
.\"O Each watch has a unique "watch descriptor", an integer
.\"O returned by
.\"O .BR inotify_add_watch (2)
.\"O when the watch is created.
各監視対象は一意の「監視対象ディスクリプタ」を持つ。
これは監視対象を作成したときに
.BR inotify_add_watch (2)
から返される整数である。

.\"O .BR inotify_rm_watch (2)
.\"O removes an item from an inotify watch list.
.BR inotify_rm_watch (2)
は inotify の監視対象リストからアイテムを削除する。

.\"O When all file descriptors referring to an inotify
.\"O instance have been closed,
.\"O the underlying object and its resources are
.\"O freed for reuse by the kernel;
.\"O all associated watches are automatically freed.
inotify インスタンスを指している
全てのファイルディスクリプタがクローズされた場合、
その下層にあるオブジェクトとそのリソースは、
カーネルで再利用するために解放される。
関連が切られた監視対象は自動的に解放される。

.\"O To determine what events have occurred, an application
.\"O .BR read (2)s
.\"O from the inotify file descriptor.
どのようなイベントが起こっていたかを知るには、
アプリケーションで inotify ファイルディスクリプタを
.BR read (2)
すればよい。
.\"O If no events have so far occurred, then,
.\"O assuming a blocking file descriptor,
.\"O .BR read (2)
.\"O will block until at least one event occurs
.\"O (unless interrupted by a signal,
.\"O in which case the call fails with the error
.\"O .BR EINTR ;
.\"O see
.\"O .BR signal (7)).
これまでに何もイベントが起こっていない場合、
停止 (blocking) モードのファイルディスクリプタであれば、
少なくとも 1 つのイベントが起こるまで
.BR read (2)
は停止する (シグナルにより割り込まれなかった場合。
シグナルによる割り込みがあった場合、呼び出しはエラー
.BR EINTR
で失敗する。
.BR signal (7)
参照)。

.\"O Each successful
.\"O .BR read (2)
.\"O returns a buffer containing one or more of the following structures:
.BR read (2)
が成功すると、以下の構造体を 1 つ以上含むバッファが返される:
.in +4n
.nf

struct inotify_event {
.\"O     int      wd;       /* Watch descriptor */
    int      wd;       /* 監視対象ディスクリプタ */
.\" FIXME . The type of the 'wd' field should probably be "int32_t".
.\" I submitted a patch to fix this.  See the LKML thread
.\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008
.\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040
.\"O     uint32_t mask;     /* Mask of events */
.\"O     uint32_t cookie;   /* Unique cookie associating related
.\"O                           events (for rename(2)) */
.\"O     uint32_t len;      /* Size of \(aqname\(aq field */
.\"O     char     name[];   /* Optional null-terminated name */
    uint32_t mask;     /* イベントのマスク */
    uint32_t cookie;   /* 関連するイベント群を関連づける
                          一意なクッキー (rename(2) 用) */
    uint32_t len;      /* \(aqname\(aq フィールドのサイズ */
    char     name[];   /* NULL で終端された任意の名前 */
};
.fi
.in

.\"O .I wd
.\"O identifies the watch for which this event occurs.
.\"O It is one of the watch descriptors returned by a previous call to
.\"O .BR inotify_add_watch (2).
.I wd
はイベント発生の監視対象を指定する。
これは、前もって行われた
.BR inotify_add_watch (2)
呼び出しで返された監視対象ディスクリプタのうちの 1 つである。

.\"O .I mask
.\"O contains bits that describe the event that occurred (see below).
.I mask
には発生したイベント (下記参照) を記述するためのビットが含まれる。

.\"O .I cookie
.\"O is a unique integer that connects related events.
.I cookie
は関連するイベントを関連づけるための一意な整数である。
.\"O Currently this is only used for rename events, and
.\"O allows the resulting pair of
.\"O .B IN_MOVE_FROM
.\"O and
.\"O .B IN_MOVE_TO
.\"O events to be connected by the application.
現在のところ、この値は rename イベントに対してのみ使われており、
結果のペアである
.B IN_MOVE_FROM
と
.B IN_MOVE_TO
イベントをアプリケーションで関連づけることができる。

.\"O The
.\"O .I name
.\"O field is only present when an event is returned
.\"O for a file inside a watched directory;
.\"O it identifies the file pathname relative to the watched directory.
.I name
フィールドは監視しているディレクトリ内のファイルに対して
イベントが返される場合のためにだけ存在する。
監視するディレクトリからのファイルの相対パス名を表す。
.\"O This pathname is null-terminated,
.\"O and may include further null bytes to align subsequent reads to a
.\"O suitable address boundary.
このパス名は NULL で終端され、
その後の読み込みで適切なアドレス境界に調整するために、
さらに NULL バイトが含まれる場合もある。

.\"O The
.\"O .I len
.\"O field counts all of the bytes in
.\"O .IR name ,
.\"O including the null bytes;
.\"O the length of each
.\"O .I inotify_event
.\"O structure is thus
.\"O .IR "sizeof(inotify_event)+len" .
.I len
フィールドは NULL バイトを含む
.I name
の全てのバイト数を表す。
よって、
.I inotify_event
構造体のサイズは
.I "sizeof(inotify_event)+len"
である。

.\"O The behavior when the buffer given to
.\"O .BR read (2)
.\"O is too small to return information about the next event depends
.\"O on the kernel version: in kernels before 2.6.21,
.\"O .BR read (2)
.\"O returns 0; since kernel 2.6.21,
.\"O .BR read (2)
.\"O fails with the error
.\"O .BR EINVAL .
.BR read (2)
に渡されたバッファが小さすぎて次のイベントに関する情報を返せない
場合の動作はカーネルのバージョンにより異なる。
2.6.21 より前のカーネルでは、
.BR read (2)
は 0 を返す。
2.6.21 以降のカーネルでは、
.BR read (2)
はエラー
.B EINVAL
で失敗する。
.\"O .SS inotify events
.SS inotify イベント
.\"O The
.\"O .BR inotify_add_watch (2)
.\"O .I mask
.\"O argument and the
.\"O .I mask
.\"O field of the
.\"O .I inotify_event
.\"O structure returned when
.\"O .BR read (2)ing
.\"O an inotify file descriptor are both bit masks identifying
.\"O inotify events.
.BR inotify_add_watch (2)
の
.I mask
引き数と、inotify ファイル構造体を
.BR read (2)
したときに返される
.I inotify_event
構造体の
.I mask
フィールドは、ともに inotify イベントを識別するための
ビットマスクである。
.\"O The following bits can be specified in
.\"O .I mask
.\"O when calling
.\"O .BR inotify_add_watch (2)
.\"O and may be returned in the
.\"O .I mask
.\"O field returned by
.\"O .BR read (2):
以下のビットが
.BR inotify_add_watch (2)
を呼ぶときの
.I mask
に指定可能であり、
.BR read (2)
で返される
.I mask
フィールドで返される:
.RS 4
.sp
.PD 0
.TP 18
.B IN_ACCESS
.\"O File was accessed (read) (*).
ファイルがアクセス (read) された。(*)
.TP
.B IN_ATTRIB
.\"O Metadata changed, e.g., permissions, timestamps, extended attributes,
.\"O link count (since Linux 2.6.25), UID, GID, etc. (*).
メタデータが変更された。
メタデータとは、例えば、許可 (permission)、タイムスタンプ、拡張属性、
リンクカウント (Linux 2.6.25 以降)、UID、GID などである。(*)
.TP
.B IN_CLOSE_WRITE
.\"O File opened for writing was closed (*).
書き込みのためにオープンされたファイルがクローズされた。(*)
.TP
.B IN_CLOSE_NOWRITE
.\"O File not opened for writing was closed (*).
書き込み以外のためにオープンされたファイルがクローズされた。(*)
.TP
.B IN_CREATE
.\"O File/directory created in watched directory (*).
監視対象ディレクトリ内でファイルやディレクトリが作成された。(*)
.TP
.B IN_DELETE
.\"O File/directory deleted from watched directory (*).
監視対象ディレクトリ内でファイルやディレクトリが削除された。(*)
.TP
.B IN_DELETE_SELF
.\"O Watched file/directory was itself deleted.
監視対象のディレクトリまたはファイル自身が削除された。
.TP
.B IN_MODIFY
.\"O File was modified (*).
ファイルが修正された。(*)
.TP
.B IN_MOVE_SELF
.\"O Watched file/directory was itself moved.
監視対象のディレクトリまたはファイル自身が移動された。
.TP
.B IN_MOVED_FROM
.\"O File moved out of watched directory (*).
ファイルが監視対象ディレクトリ外へ移動された。(*)
.TP
.B IN_MOVED_TO
.\"O File moved into watched directory (*).
ファイルが監視対象ディレクトリ内へ移動された。(*)
.TP
.B IN_OPEN
.\"O File was opened (*).
ファイルがオープンされた。(*)
.PD
.RE
.PP
.\"O When monitoring a directory,
.\"O the events marked with an asterisk (*) above can occur for
.\"O files in the directory, in which case the
.\"O .I name
.\"O field in the returned
.\"O .I inotify_event
.\"O structure identifies the name of the file within the directory.
ディレクトリを監視する場合、
上記でアスタリスク (*) を付けたイベントは、
そのディレクトリ内のファイルに対して発生する。
このとき
.I inotify_event
構造体で返される
.I name
フィールドは、ディレクトリ内のファイル名を表す。
.PP
.\"O The
.\"O .B IN_ALL_EVENTS
.\"O macro is defined as a bit mask of all of the above events.
.\"O This macro can be used as the
.\"O .I mask
.\"O argument when calling
.\"O .BR inotify_add_watch (2).
.B IN_ALL_EVENTS
マクロは上記のイベント全てのマスクとして定義される。
このマクロは
.BR inotify_add_watch (2)
を呼び出すときの
.I mask
引き数として使える。

.\"O Two additional convenience macros are
.\"O .BR IN_MOVE ,
.\"O which equates to
.\"O IN_MOVED_FROM|IN_MOVED_TO,
.\"O and
.\"O .B IN_CLOSE
.\"O which equates to
.\"O IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.
さらに 2 つの便利なマクロがある。
.B IN_MOVE
は
IN_MOVED_FROM|IN_MOVED_TO
と等しく、
.B IN_CLOSE
は
IN_CLOSE_WRITE|IN_CLOSE_NOWRITE
と等しい。
.PP
.\"O The following further bits can be specified in
.\"O .I mask
.\"O when calling
.\"O .BR inotify_add_watch (2):
その他にも以下のビットを
.BR inotify_add_watch (2)
を呼ぶときの
.I mask
に指定できる:
.RS 4
.sp
.PD 0
.TP 18
.B IN_DONT_FOLLOW
.\"O Don't dereference \fIpathname\fP if it is a symbolic link
.\"O (since Linux 2.6.15).
\fIpathname\fP がシンボリックリンクである場合に辿らない。
(Linux 2.6.15 以降)
.TP
.B IN_MASK_ADD
.\"O Add (OR) events to watch mask for this pathname if
.\"O it already exists (instead of replacing mask).
\fIpathname\fP に対する監視マスクが既に存在する場合、
(マスクの置き換えではなく) イベントを追加 (OR) する。
.TP
.B IN_ONESHOT
.\"O Monitor \fIpathname\fP for one event, then remove from
.\"O watch list.
1 つのイベントについて \fIpathname\fP を監視し、
イベントが発生したら監視対象リストから削除する。
.TP
.\"O .BR IN_ONLYDIR " (since Linux 2.6.15)"
.BR IN_ONLYDIR " (Linux 2.6.15 以降)"
.\"O Only watch \fIpathname\fP if it is a directory.
\fIpathname\fP がディレクトリの場合にのみ監視する。
.PD
.RE
.PP
.\"O The following bits may be set in the
.\"O .I mask
.\"O field returned by
.\"O .BR read (2):
以下のビットが
.BR read (2)
で返される
.I mask
フィールドに設定される:
.RS 4
.sp
.PD 0
.TP 18
.B IN_IGNORED
.\"O Watch was removed explicitly (\fBinotify_rm_watch\fP(2))
.\"O or automatically (file was deleted, or file system was unmounted).
監視対象が (\fBinotify_rm_watch\fP(2) により) 明示的に
削除された。もしくは (ファイルの削除、またはファイル
システムのアンマウントにより) 自動的に削除された。
.TP
.B IN_ISDIR
.\"O Subject of this event is a directory.
このイベントの対象がディレクトリである。
.TP
.B IN_Q_OVERFLOW
.\"O Event queue overflowed (\fIwd\fP is \-1 for this event).
イベントキューが溢れた (このイベントの場合、\fIwd\fP は \-1 である)。
.TP
.B IN_UNMOUNT
.\"O File system containing watched object was unmounted.
監視対象オブジェクトを含むファイルシステムがアンマウントされた。
.PD
.RE
.\"O .SS /proc interfaces
.SS /proc インターフェース
.\"O The following interfaces can be used to limit the amount of
.\"O kernel memory consumed by inotify:
以下のインターフェースは、inotify で消費される
カーネルメモリの総量を制限するのに使用できる:
.TP
.I /proc/sys/fs/inotify/max_queued_events
.\"O The value in this file is used when an application calls
.\"O .BR inotify_init (2)
.\"O to set an upper limit on the number of events that can be
.\"O queued to the corresponding inotify instance.
このファイルの値は、アプリケーションが
.BR inotify_init (2)
を呼び出すときに使用され、対応する inotify インスタンスについて
キューに入れられるイベントの数の上限を設定する。
.\"O Events in excess of this limit are dropped, but an
.\"O .B IN_Q_OVERFLOW
.\"O event is always generated.
この制限を超えたイベントは破棄されるが、
.B IN_Q_OVERFLOW
イベントが常に生成される。
.TP
.I /proc/sys/fs/inotify/max_user_instances
.\"O This specifies an upper limit on the number of inotify instances
.\"O that can be created per real user ID.
1 つの実ユーザ ID に対して生成できる
inotify インスタンスの数の上限を指定する。
.TP
.I /proc/sys/fs/inotify/max_user_watches
.\"O This specifies an upper limit on the number of watches
.\"O that can be created per real user ID.
作成可能な監視対象の数の実 UID 単位の上限を指定する。
.\"O .SH "VERSIONS"
.SH バージョン
.\"O Inotify was merged into the 2.6.13 Linux kernel.
.\"O The required library interfaces were added to glibc in version 2.4.
.\"O .RB ( IN_DONT_FOLLOW ,
.\"O .BR IN_MASK_ADD ,
.\"O and
.\"O .B IN_ONLYDIR
.\"O were only added in version 2.5.)
inotify は 2.6.13 の Linux カーネルに組込まれた。
これに必要なライブラリのインターフェースは、
glibc のバージョン 2.4 に追加された
.RB ( IN_DONT_FOLLOW ,
.BR IN_MASK_ADD ,
.B IN_ONLYDIR
だけはバージョン 2.5 で追加された)。
.\"O .SH "CONFORMING TO"
.SH 準拠
.\"O The inotify API is Linux-specific.
inotify API は Linux 独自のものである。
.\"O .SH "NOTES"
.SH 注意
.\"O Inotify file descriptors can be monitored using
.\"O .BR select (2),
.\"O .BR poll (2),
.\"O and
.\"O .BR epoll (7).
inotify ファイルディスクリプタは
.BR select (2),
.BR poll (2),
.BR epoll (7)
を使って監視できる。
.\"O When an event is available, the file descriptor indicates as readable.
イベントがある場合、ファイルディスクリプタは読み込み可能と通知する。

.\"O Since Linux 2.6.25,
.\"O signal-driven I/O notification is available for inotify file descriptors;
.\"O see the discussion of
.\"O .B F_SETFL
.\"O (for setting the
.\"O .B O_ASYNC
.\"O flag),
.\"O .BR F_SETOWN ,
.\"O and
.\"O .B F_SETSIG
.\"O in
.\"O .BR fcntl (2).
Linux 2.6.25 以降では、シグナル駆動 (signal-driven) I/O の通知が
inotify ファイルディスクリプタについて利用可能である。
.BR fcntl (2)
に書かれている
.RB ( O_ASYNC
フラグを設定するための)
.BR F_SETFL ,
.BR F_SETOWN ,
.B F_SETSIG
の議論を参照のこと。
.\"O The
.\"O .I siginfo_t
.\"O structure (described in
.\"O .BR sigaction (2))
.\"O that is passed to the signal handler has the following fields set:
.\"O .IR si_fd
.\"O is set to the inotify file descriptor number;
.\"O .IR si_signo
.\"O is set to the signal number;
.\"O .IR si_code
.\"O is set to
.\"O .BR POLL_IN ;
.\"O and
.\"O .B POLLIN
.\"O is set in
.\"O .IR si_band .
シグナルハンドラに渡される
.I siginfo_t
構造体は、以下のフィールドが設定される
.RI ( siginfo_t
は
.BR sigaction (2)
で説明されている)。
.I si_fd
には inotify ファイルディスクリプタ番号が、
.I si_signo
にはシグナル番号が、
.I si_code
には
.BR POLL_IN
が、
.I si_band
には
.B POLLIN
が設定される。

.\"O If successive output inotify events produced on the
.\"O inotify file descriptor are identical (same
.\"O .IR wd ,
.\"O .IR mask ,
.\"O .IR cookie ,
.\"O and
.\"O .IR name )
.\"O then they are coalesced into a single event if the
.\"O older event has not yet been read (but see BUGS).
inotify ファイルディスクリプタに対して
連続して生成される出力 inotify イベントが同一の場合
.RI ( wd ,
.IR mask ,
.IR cookie ,
.I name
が等しい場合)、
前のイベントがまだ読み込まれていなければ、
連続するイベントが 1 つのイベントにまとめられる
(ただし「バグ」の節も参照のこと)。

.\"O The events returned by reading from an inotify file descriptor
.\"O form an ordered queue.
.\"O Thus, for example, it is guaranteed that when renaming from
.\"O one directory to another, events will be produced in the
.\"O correct order on the inotify file descriptor.
.\"Osato:
.\"Osato: 以下の訳が上手くできていない気がする。
.\"Osato:
inotify ファイルディスクリプタの読み込みで返されるイベントは、
順序付けられたキューになる。
従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、
inotify ファイルディスクリプタについての正しい順番で
イベントが生成されることが保証される。

.\"O The
.\"O .B FIONREAD
.\"O .BR ioctl (2)
.\"O returns the number of bytes available to read from an
.\"O inotify file descriptor.
.B FIONREAD
.BR ioctl (2)
は inotify ファイルディスクリプタから何バイト読み込めるかを返す。

.\"O Inotify monitoring of directories is not recursive:
.\"O to monitor subdirectories under a directory,
.\"O additional watches must be created.
inotify によるディレクトリの監視は再帰的に行われない:
あるディレクトリ以下のサブディレクトリを監視する場合、
監視対象を追加で作成しなければならない。
.\"O .SH "BUGS"
.SH バグ
.\"O In kernels before 2.6.16, the
.\"O .B IN_ONESHOT
.\"O .I mask
.\"O flag does not work.
2.6.16 以前のカーネルでは
.B IN_ONESHOT
.I mask
フラグが働かない。

.\"O Before kernel 2.6.25,
.\"O the kernel code that was intended to coalesce successive identical events
.\"O (i.e., the two most recent events could potentially be coalesced
.\"O if the older had not yet been read)
.\"O instead checked if the most recent event could be coalesced with the
.\"O .I oldest
.\"O unread event.
カーネル 2.6.25 より前では、
連続する同一のイベントを一つにまとめることを意図したコード
(古い方のイベントがまだ読み込まれていない場合に、
最新の 2 つのイベントを一つにまとめられる可能性がある) が、
最新のイベントが「最も古い」読み込まれていないイベントとまとめられるか
をチェックするようになっていた。
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR inotify_add_watch (2),
.BR inotify_init (2),
.BR inotify_init1 (2),
.BR inotify_rm_watch (2),
.BR read (2),
.BR stat (2),
.IR Documentation/filesystems/inotify.txt .