| 1 | |
| 2 |
|
| 3 | ============================
|
| 4 | Linux Directory Notification
|
| 5 | ============================
|
| 6 |
|
| 7 | Stephen Rothwell <[email protected]>
|
| 8 |
|
| 9 | The intention of directory notification is to allow user applications
|
| 10 | to be notified when a directory, or any of the files in it, are changed.
|
| 11 | The basic mechanism involves the application registering for notification
|
| 12 | on a directory using a fcntl(2) call and the notifications themselves
|
| 13 | being delivered using signals.
|
| 14 |
|
| 15 | The application decides which "events" it wants to be notified about.
|
| 16 | The currently defined events are:
|
| 17 |
|
| 18 | ========= =====================================================
|
| 19 | DN_ACCESS A file in the directory was accessed (read)
|
| 20 | DN_MODIFY A file in the directory was modified (write,truncate)
|
| 21 | DN_CREATE A file was created in the directory
|
| 22 | DN_DELETE A file was unlinked from directory
|
| 23 | DN_RENAME A file in the directory was renamed
|
| 24 | DN_ATTRIB A file in the directory had its attributes
|
| 25 | changed (chmod,chown)
|
| 26 | ========= =====================================================
|
| 27 |
|
| 28 | Usually, the application must reregister after each notification, but
|
| 29 | if DN_MULTISHOT is or'ed with the event mask, then the registration will
|
| 30 | remain until explicitly removed (by registering for no events).
|
| 31 |
|
| 32 | By default, SIGIO will be delivered to the process and no other useful
|
| 33 | information. However, if the F_SETSIG fcntl(2) call is used to let the
|
| 34 | kernel know which signal to deliver, a siginfo structure will be passed to
|
| 35 | the signal handler and the si_fd member of that structure will contain the
|
| 36 | file descriptor associated with the directory in which the event occurred.
|
| 37 |
|
| 38 | Preferably the application will choose one of the real time signals
|
| 39 | (SIGRTMIN + <n>) so that the notifications may be queued. This is
|
| 40 | especially important if DN_MULTISHOT is specified. Note that SIGRTMIN
|
| 41 | is often blocked, so it is better to use (at least) SIGRTMIN + 1.
|
| 42 |
|
| 43 | Implementation expectations (features and bugs :-))
|
| 44 | ---------------------------------------------------
|
| 45 |
|
| 46 | The notification should work for any local access to files even if the
|
| 47 | actual file system is on a remote server. This implies that remote
|
| 48 | access to files served by local user mode servers should be notified.
|
| 49 | Also, remote accesses to files served by a local kernel NFS server should
|
| 50 | be notified.
|
| 51 |
|
| 52 | In order to make the impact on the file system code as small as possible,
|
| 53 | the problem of hard links to files has been ignored. So if a file (x)
|
| 54 | exists in two directories (a and b) then a change to the file using the
|
| 55 | name "a/x" should be notified to a program expecting notifications on
|
| 56 | directory "a", but will not be notified to one expecting notifications on
|
| 57 | directory "b".
|
| 58 |
|
| 59 | Also, files that are unlinked, will still cause notifications in the
|
| 60 | last directory that they were linked to.
|
| 61 |
|
| 62 | Configuration
|
| 63 | -------------
|
| 64 |
|
| 65 | Dnotify is controlled via the CONFIG_DNOTIFY configuration option. When
|
| 66 | disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.
|
| 67 |
|
| 68 | Example
|
| 69 | -------
|
| 70 | See tools/testing/selftests/filesystems/dnotify_test.c for an example.
|
| 71 |
|
| 72 | NOTE
|
| 73 | ----
|
| 74 | Beginning with Linux 2.6.13, dnotify has been replaced by inotify.
|
| 75 | See Documentation/filesystems/inotify.rst for more information on it.
|