Replaced exhaustive search with a binary lookup in watch list.
[erlang-gen_inotify.git] / README.md
1 inotify bindings for Erlang
2 ===========================
3
4 `gen_inotify` is an Erlang bindings library to `inotify(7)` Linux subsystem to
5 watch filesystem events.
6
7 Usage example
8 -------------
9
10     1> file:make_dir("/tmp/watch").
11     ok
12     2> {ok, H} = gen_inotify:open().
13     {ok,#Port<0.620>}
14     3> gen_inotify:add(H, "/tmp/watch", [if_dir, create, delete]).
15     ok
16     4> file:make_dir("/tmp/watch/subdir").
17     ok
18     5> file:del_dir("/tmp/watch/subdir").
19     ok
20     6> flush().
21     Shell got {inotify,#Port<0.620>,"/tmp/watch/subdir",0,[is_dir,create]}
22     Shell got {inotify,#Port<0.620>,"/tmp/watch/subdir",0,[is_dir,delete]}
23     ok
24
25 `/proc` interface
26 -----------------
27
28 *inotify* has per-UID limits on number of sockets, events, and watches. These
29 limits can be read and modified using `/proc` interface.
30
31 * `/proc/sys/fs/inotify/max_user_instances` -- limit on number of open
32   *inotify* descriptors
33 * `/proc/sys/fs/inotify/max_user_watches` -- limit on total number of watched
34   objects (files and directories) across the *inotify* descriptors
35 * `/proc/sys/fs/inotify/max_queued_events` -- maximum number of unread
36   filesystem events before a queue overflow message is generated and the
37   events start being dropped
38
39 Details are described in `inotify(7)` man page.
40
41 Known limitations and problems
42 ------------------------------
43
44 * watching a directory recursively in a robust way is impossible (e.g. all
45   `open(2)` events between subdirectory creation and adding it to *inotify*
46   descriptor are lost), so "best effort" heuristic is used
47 * file renames are not tracked by the port driver, thus messages about a file
48   that got renamed carry the file's original path, and removing it from
49   watching requires the original name as well
50
51 Requirements
52 ------------
53
54 Linux kernel 2.6.36 or above and glibc 2.9 or above. These requirements are
55 satisfied in Debian 7 Squeeze and CentOS 7.0.
56
57 Contact and license
58 -------------------
59
60 `gen_inotify` library is written by Stanislaw Klekot <dozzie at jarowit.net>.
61 The primary distribution point is <http://dozzie.jarowit.net/>.
62
63 `gen_inotify` library is distributed under 3-clause BSD license. See COPYING
64 file for details.