--- name: "inotify_rm_watch" section: "2" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/inotify" --- # inotify\_rm\_watch(2) monitor file system events Part of [inotify(2)](/inotify/2.md). ## NAME **inotify\_init**, **inotify\_init1**, **inotify\_add\_watch**, **inotify\_add\_watch\_at**, **inotify\_rm\_watch** – monitor file system events ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** *int*\ **inotify\_init**(); *int*\ **inotify\_init1**(*int flags*); *int*\ **inotify\_add\_watch**(*int fd*, *const char \*pathname*, *uint32\_t mask*); *int*\ **inotify\_add\_watch\_at**(*int fd*, *int dfd*, *const char \*pathname*, *uint32\_t mask*); *int*\ **inotify\_rm\_watch**(*int fd*, *uint32\_t wd*); ``` struct inotify_event { int wd; /* Watch descriptor */ uint32_t mask; /* Event and flags */ uint32_t cookie; /* Unique ID which links rename events */ uint32_t len; /* Name field size, including nul bytes */ char name[0]; /* Filename (nul-terminated) */ }; ``` ## DESCRIPTION The inotify system calls provide an interface to monitor file system events. They aim to be compatible with the Linux inotify interface. The provided functionality is similar to the EVFILT\_VNODE filter of the [kevent(2)](/kevent/2.md) system call, but further allows monitoring of a directory without needing to open each object in that directory. This avoids races and reduces the number of file descriptors needed to monitor a large file hierarchy. inotify allows one or more file system objects, generally files or directories, to be watched for events, such as file open or close. Watched objects are associated with a file descriptor returned by **inotify\_init**() or **inotify\_init1**(). When an event occurs, a record describing the event becomes available for reading from the inotify file descriptor. Each inotify descriptor thus refers to a queue of events waiting to be read. inotify descriptors are inherited across [fork(2)](/fork/2.md) calls and may be passed to other processes via [unix(4)](/unix/4.md) sockets. The **inotify\_init1**() system call accepts two flags. The IN\_NONBLOCK flag causes the inotify descriptor to be opened in non-blocking mode, such that [read(2)](/read/2.md) calls will not block if no records are available to consume, and will instead return EWOULDBLOCK. The IN\_CLOEXEC flag causes the inotify descriptor to be closed automatically when [execve(2)](/execve/2.md) is called. To watch a file or directory, the **inotify\_add\_watch**() or **inotify\_add\_watch\_at**() system calls must be used. They take a path and a mask of events to watch for, and return a “watch descriptor”, a non-negative integer which uniquely identifies the watched object within the inotify descriptor. The **inotify\_rm\_watch**() system call removes a watch from an inotify descriptor. When watching a directory, objects within the directory are monitored for events as well as the directory itself. A record describing an inotify event consists of a “struct inotify\_event” followed by the name of the object in the directory being watched. If the watched object itself generates an event, no name is present. Extra nul bytes may follow the file name in order to provide alignment for a subsequent record. The following events are defined: - IN\_ACCESS A file's contents were accessed, e.g., by [read(2)](/read/2.md) [copy\_file\_range(2)](/copy_file_range/2.md), [sendfile(2)](/sendfile/2.md), or [getdirentries(2)](/getdirentries/2.md). - IN\_ATTRIB A file's metadata was changed, e.g., by [chmod(2)](/chmod/2.md) or [unlink(2)](/unlink/2.md). - IN\_CLOSE\_WRITE A file that was previously opened for writing was closed. - IN\_CLOSE\_NOWRITE A file that was previously opened read-only was closed. - IN\_CREATE A file within a watched directory was created, e.g., by [open(2)](/open/2.md), [mkdir(2)](/mkdir/2.md), [symlink(2)](/symlink/2.md), [mknod(2)](/mknod/2.md), or [bind(2)](/bind/2.md). - IN\_DELETE A file or directory within a watched directory was removed. - IN\_DELETE\_SELF The watched file or directory itself was deleted. This event is generated only when the link count of the file drops to zero. - IN\_MODIFY A file's contents were modified, e.g., by [write(2)](/write/2.md) or [copy\_file\_range(2)](/copy_file_range/2.md). - IN\_MOVE\_SELF The watched file or directory itself was renamed. - IN\_MOVED\_FROM A file or directory was moved from a watched directory. - IN\_MOVED\_TO A file or directory was moved into a watched directory. A [rename(2)](/rename/2.md) call thus may generate two events, one for the old name and one for the new name. These are linked together by the *cookie* field in the inotify record, which can be compared to link the two records to the same event. - IN\_OPEN A file was opened. Some additional flags may be set in inotify event records: - IN\_IGNORED When a watch is removed from a file, for example because it was created with the IN\_ONESHOT flag, the file was deleted, or the watch was explicitly removed with **inotify\_rm\_watch**(), an event with this mask is generated to indicate that the watch will not generate any more events. Once this event is generated, the watch is automatically removed, and in particular should not be removed manually with **inotify\_rm\_watch**(). - IN\_ISDIR When the subject of an event is a directory, this flag is set in the *mask* - IN\_Q\_OVERFLOW One or more events were dropped, for example because of a kernel memory allocation failure or because the event queue size hit a limit. - IN\_UNMOUNT The filesystem containing the watched object was unmounted. A number of flags may also be specified in the *mask* given to **inotify\_add\_watch**() and **inotify\_add\_watch\_at**(): - IN\_DONT\_FOLLOW If *pathname* is a symbolic link, do not follow it. - IN\_EXCL\_UNLINK This currently has no effect, see the BUGS section. - IN\_MASK\_ADD When adding a watch to an object, and that object is already watched by the same inotify descriptor, by default the mask of the existing watch is overwritten. When IN\_MASK\_ADD is specified, the mask of the existing watch is instead logically ORed with the new mask. - IN\_MASK\_CREATE When **inotify\_add**(*watch*) is used to add a watch to an object, IN\_MASK\_CREATE is specified, and that object is already watched by the same inotify descriptor, return an error instead of updating the existing watch. - IN\_ONESHOT Monitor the object for a single event, after which the watch is automatically removed. As part of removal, a IN\_IGNORED event is generated. - IN\_ONLYDIR When creating a watch, fail with ENOTDIR if the path does not refer to a directory. ## SYSCTL VARIABLES The following variables are available as both [sysctl(8)](/sysctl/8.md) variables and [loader(8)](/loader/8.md) tunables: - *vfs.inotify.max\_events* The maximum number of inotify records that can be queued for a single inotify descriptor. Records in excess of this limit are discarded, and a single event with mask equal to IN\_Q\_OVERFLOW will be present in the queue. - *vfs.inotify.max\_user\_instances* The maximum number of inotify descriptors that can be created by a single user. - *vfs.inotify.max\_user\_watches* The maximum number of inotify watches per user. ## EXAMPLES See the example program in */usr/share/examples/inotify/inotify.c*. ## ERRORS The **inotify\_init**() and **inotify\_init1**() functions will fail if: - \[ENFILE\] The system limit on the total number of open files has been reached. - \[EMFILE\] A per-process limit on the number of open files has been reached. - \[EMFILE\] The system limit on the number of inotify descriptors has been reached. - \[EINVAL\] An unrecognized flag was passed to **inotify\_init1**(). The **inotify\_add\_watch**() and **inotify\_add\_watch\_at**() system calls will fail if: - \[EBADF\] The *fd* parameter is not a valid file descriptor. - \[EINVAL\] The *fd* parameter is not an inotify descriptor. - \[EINVAL\] The *mask* parameter does not specify an event, or the IN\_MASK\_CREATE and IN\_MASK\_ADD flags are both set, or an unrecognized flag was passed. - \[ENOTDIR\] The *pathname* parameter refers to a file that is not a directory, and the IN\_ONLYDIR flag was specified. - \[ENOSPC\] The per-user limit on the total number of inotify watches has been reached. - \[ECAPMODE\] The process is in capability mode and **inotify\_add\_watch**() was called, or **inotify\_add\_watch\_at**() was called with AT\_FDCWD as the directory file descriptor *dfd*. - \[ENOTCAPABLE\] The process is in capability mode and *pathname* contains a “..” component leading to a directory outside the directory hierarchy specified by *dfd*. The **inotify\_rm\_watch**() system call will fail if: - \[EBADF\] The *fd* parameter is not a valid file descriptor. - \[EINVAL\] The *fd* parameter is not an inotify descriptor. - \[EINVAL\] The *wd* parameter is not a valid watch descriptor. ## SEE ALSO [kevent(2)](/kevent/2.md), [capsicum(4)](/capsicum/4.md) ## STANDARDS The **inotify\_init** interface originates from Linux and is non-standard. This implementation aims to be compatible with that of Linux and is based on the documentation available at *https://man7.org/linux/man-pages/man7/inotify.7.html*. ## HISTORY The inotify system calls first appeared in FreeBSD 15.0. ## BUGS If a file in a watched directory has multiple hard links, an access via any hard link for that file will generate an event, even if the accessed link belongs to an unwatched directory. This is not the case for the Linux implementation, where only accesses via the hard link in the watched directory will generate an event. If a watched directory contains multiple hard links of a file, an event on one of the hard links will generate an inotify record for each link in the directory. When a file is unlinked, no more events will be generated for that file, even if it continues to be accessed. By default, the Linux implementation will continue to generate events in this case. Thus, the FreeBSD implementation behaves as though IN\_EXCL\_UNLINK is always set. Some inotify events rely on the kernel's name cache in order to determine the name of the file being accessed. Some filesystems do not use the name cache, for instance [devfs(4)](/devfs/4.md), and [tmpfs(4)](/tmpfs/4.md) mounts with the nonc option set. inotify may not reliably deliver events for files on such filesystems. inotify does not deliver events for [devfs(4)](/devfs/4.md) files so as to avoid leaking potentially sensitive timing information. For instance, IN\_ACCESS events on */dev/input* could be used to determine information about keyboard input from a different user. A watch on a [devfs(4)](/devfs/4.md) file or directory may be created, but will not deliver any events.