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