+The inotify API identifies events via watch descriptors. It is the
+application's responsibility to cache a mapping (if one is needed) between
+watch descriptors and pathnames. Be aware that directory renamings may
+affect multiple cached pathnames.
+
+inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下の
+サブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。
+大きなディレクトリツリーの場合には、この作業にかなり時間がかかることがある。
+
+If monitoring an entire directory subtree, and a new subdirectory is created
+in that tree or an existing directory is renamed into that tree, be aware
+that by the time you create a watch for the new subdirectory, new files (and
+subdirectories) may already exist inside the subdirectory. Therefore, you
+may want to scan the contents of the subdirectory immediately after adding
+the watch (and, if desired, recursively add watches for any subdirectories
+that it contains).
+
+Note that the event queue can overflow. In this case, events are lost.
+Robust applications should handle the possibility of lost events
+gracefully. For example, it may be necessary to rebuild part or all of the
+application cache. (One simple, but possibly expensive, approach is to
+close the inotify file descriptor, empty the cache, create a new inotify
+file descriptor, and then re\-create watches and cache entries for the
+objects to be monitored.)
+.SS "rename() イベントの取り扱い"
+As noted above, the \fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP event pair that is
+generated by \fBrename\fP(2) can be matched up via their shared cookie value.
+However, the task of matching has some challenges.
+
+These two events are usually consecutive in the event stream available when
+reading from the inotify file descriptor. However, this is not guaranteed.
+If multiple processes are triggering events for monitored objects, then (on
+rare occasions) an arbitrary number of other events may appear between the
+\fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP events.
+
+Matching up the \fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP event pair generated by
+\fBrename\fP(2) is thus inherently racy. (Don't forget that if an object is
+renamed outside of a monitored directory, there may not even be an
+\fBIN_MOVED_TO\fP event.) Heuristic approaches (e.g., assume the events are
+always consecutive) can be used to ensure a match in most cases, but will
+inevitably miss some cases, causing the application to perceive the
+\fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP events as being unrelated. If watch
+descriptors are destroyed and re\-created as a result, then those watch
+descriptors will be inconsistent with the watch descriptors in any pending
+events. (Re\-creating the inotify file descriptor and rebuilding the cache
+may be useful to deal with this scenario.)
+
+Applications should also allow for the possibility that the \fBIN_MOVED_FROM\fP
+event was the last event that could fit in the buffer returned by the
+current call to \fBread\fP(2), and the accompanying \fBIN_MOVED_TO\fP event might
+be fetched only on the next \fBread\fP(2).