Linux Directory Notification

등록 방식, event mask와 multishot

directory notification은 directory 자체나 그 안의 file이 바뀔 때 userspace application에 알리기 위한 기능입니다. application은 `fcntl(2)`로 directory notification을 등록하고 kernel은 signal로 알림을 전달합니다.

`DN_ACCESS`는 directory 안 file의 read 접근, `DN_MODIFY`는 write 또는 truncate, `DN_CREATE`는 생성, `DN_DELETE`는 unlink, `DN_RENAME`은 이름 변경, `DN_ATTRIB`는 `chmod`나 `chown`에 따른 attribute 변경을 나타냅니다.

보통 application은 notification을 받을 때마다 다시 등록해야 합니다. event mask에 `DN_MULTISHOT`을 OR하면 event를 하나도 등록하지 않는 방식으로 명시적으로 제거할 때까지 등록이 유지됩니다.

.. SPDX-License-Identifier: GPL-2.0

============================
Linux Directory Notification
============================

           Stephen Rothwell <[email protected]>

The intention of directory notification is to allow user applications
to be notified when a directory, or any of the files in it, are changed.
The basic mechanism involves the application registering for notification
on a directory using a fcntl(2) call and the notifications themselves
being delivered using signals.

The application decides which "events" it wants to be notified about.
The currently defined events are:

        =========        =====================================================
        DN_ACCESS        A file in the directory was accessed (read)
        DN_MODIFY        A file in the directory was modified (write,truncate)
        DN_CREATE        A file was created in the directory
        DN_DELETE        A file was unlinked from directory
        DN_RENAME        A file in the directory was renamed
        DN_ATTRIB        A file in the directory had its attributes
                        changed (chmod,chown)
        =========        =====================================================

Usually, the application must reregister after each notification, but
if DN_MULTISHOT is or'ed with the event mask, then the registration will
remain until explicitly removed (by registering for no events).

SIGIO, F_SETSIG와 realtime queue

기본값은 process에 `SIGIO`만 전달하며 다른 유용한 정보는 없습니다. `F_SETSIG` `fcntl(2)` call로 전달할 signal을 kernel에 알려 주면 signal handler에 `siginfo` structure가 전달되고, `si_fd`에는 event가 발생한 directory의 file descriptor가 들어갑니다.

notification이 queue될 수 있도록 realtime signal인 `SIGRTMIN + <n>`을 선택하는 것이 좋습니다. `DN_MULTISHOT`을 쓸 때 특히 중요합니다. `SIGRTMIN` 자체는 흔히 block되어 있으므로 최소 `SIGRTMIN + 1`을 사용하는 편이 낫습니다.

By default, SIGIO will be delivered to the process and no other useful
information.  However, if the F_SETSIG fcntl(2) call is used to let the
kernel know which signal to deliver, a siginfo structure will be passed to
the signal handler and the si_fd member of that structure will contain the
file descriptor associated with the directory in which the event occurred.

Preferably the application will choose one of the real time signals
(SIGRTMIN + <n>) so that the notifications may be queued.  This is
especially important if DN_MULTISHOT is specified.  Note that SIGRTMIN
is often blocked, so it is better to use (at least) SIGRTMIN + 1.

Remote access와 hard link 한계

실제 filesystem이 remote server에 있어도 local access로 발생한 변화에는 notification이 동작해야 합니다. local userspace server가 제공하는 file에 대한 remote access와 local kernel NFS server가 제공하는 file에 대한 remote access도 notification 대상이어야 합니다.

filesystem code에 미치는 영향을 줄이기 위해 hard link 문제는 무시합니다. file `x`가 directory `a`와 `b`에 함께 존재할 때 `a/x`라는 이름으로 변경하면 `a`를 감시하는 program에는 알리지만 `b`를 감시하는 program에는 알리지 않습니다.

unlink된 file도 마지막으로 연결되어 있던 directory에서 계속 notification을 발생시킵니다.

Implementation expectations (features and bugs :-))
---------------------------------------------------

The notification should work for any local access to files even if the
actual file system is on a remote server.  This implies that remote
access to files served by local user mode servers should be notified.
Also, remote accesses to files served by a local kernel NFS server should
be notified.

In order to make the impact on the file system code as small as possible,
the problem of hard links to files has been ignored.  So if a file (x)
exists in two directories (a and b) then a change to the file using the
name "a/x" should be notified to a program expecting notifications on
directory "a", but will not be notified to one expecting notifications on
directory "b".

Also, files that are unlinked, will still cause notifications in the
last directory that they were linked to.

CONFIG_DNOTIFY, test와 inotify 대체

dnotify는 `CONFIG_DNOTIFY` configuration option으로 제어합니다. 비활성화되어 있으면 `fcntl(fd, F_NOTIFY, ...)`가 `-EINVAL`을 반환합니다.

사용 예제는 source path `tools/testing/selftests/filesystems/dnotify_test.c`에 있습니다.

Linux 2.6.13부터 dnotify는 inotify로 대체되었습니다. 자세한 내용은 `Documentation/filesystems/inotify.rst`를 참고합니다.

Configuration
-------------

Dnotify is controlled via the CONFIG_DNOTIFY configuration option.  When
disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.

Example
-------
See tools/testing/selftests/filesystems/dnotify_test.c for an example.

NOTE
----
Beginning with Linux 2.6.13, dnotify has been replaced by inotify.
See Documentation/filesystems/inotify.rst for more information on it.