inotify FAQ (Frequently Asked Questions)

Q: What is inotify?
inotify is an inode-base file system notification mechanism. See About for more details.
Q: What can I use inotify for?
inotify is intended for use in all cases of monitoring filesystem events. See Why to use for more details.
Q: Which kernels do support inotify?
inotify has been merged to 2.6.13. Your kernel must be configured to compile inotify in (CONFIG_INOTIFY).
Q: Why use inotify and not dnotify?
There are many reasons. The first one is that dnotify sucks. The second one is that dnotify sucks much. The third one is that dnotify sucks very much... See Why to use for more information.
Q: How to use inotify?
The main concept can be briefly described in these steps:
1. Create an inotify instance (inotify_init()).
2. Add as watches as you want (inotify_add_watch()).
3. Read events through read().
4. For non-blocking mode do the same as for network sockets etc.
5. If you don't want use a watch, remove it by inotify_rm_watch().
6. When done, call close() like on another file descriptor.
Q: Need I any library for inotify?
No, you don't. inotify is based on system calls, not library functions. All you need is a inotify-enabled kernel. The header files noted somewhere only help to use inotify simplier way (e.g. you needn't search for syscall numbers for your platform) but they are not essential.
Q: Is there a license restriction (due to the GPL-ed kernel)?
No. System calls are considered as "normal use". It's similar to use any other system calls such as read() or gettimeofday(). The inotify implementation itself (in the kernel) is of course licensed under GPL and if you want to use this code you must keep the same license.
Q: Is there a C++ interface for inotify?
Yes, inotify-cxx. This interface uses a few simple classes which provide basic inotify functionality and exception-based error handling.
Q: Which languages (other than C/C++) can I use with inotify?
There are some bindings for various languages. See Links.
Q: Can I use inotify in the non-blocking mode?
Of course. Use the regular fcntl() function to enable the O_NONBLOCK flag.
Q: Can I use select() or poll() for monitoring inotify descriptors?
Absolutely. inotify file descriptor can be used the same way as any other file descriptors. Use select(), poll() or epoll() as you want.
Q: Can I use inotify asynchronously?
Although it is not recommended you can. But use a realtime signal rather than the standard SIGIO one. For switching to asynchronous mode call fcntl() with the F_SETOWN flag similarily to the normal async I/O.
Q: Can I use inotify through signals?
See above. It's better to use some of realtime signals because these are queued. "Normal" signals like SIGIO are bitwise-based.
Q: Is there a FIONREAD ioctl() call?
Yes it is. Enjoy!
Q: Are there any limitations for use of inotify?
Yes. Some filesystems (e.g. procfs or some network filesystems) don't emit events in some cases.
Q: What does happen if the watched filesystem is unmounted?
If a filesystem is being unmounted and there is a inotify watch the kernel emits the IN_UNMOUNT event.
Q: Can I use inotify outside Linux?
No. It is Linux specific. But other systems have similar mechanisms.
Q: Can I monitor the whole subtree under some directory?
Not directly. You can monitor only a file or a directory (together with all files in this directory) but nothing below. If you want to do this you must create as many watches as many directories you would like to monitor.
Q: Can I watch sysfs (procfs, nfs...)?
Simply spoken: yes, but with some limitations. These limitations vary between kernel versions and tend to get smaller. Please read information about particular filesystems.
Q: How to catch exactly one event?
Use the IN_ONESHOT flag. You will receive only the first occurred event.
Q: What means IN_IGNORED and when is emitted?
IN_IGNORED is emitted when a watch is removed. You should catch this event and handle it properly.
Q: What means IN_Q_OVERFLOW?
IN_Q_OVERFLOW is emitted when the appropriate queue is full and can't take more events. If this event occurs frequently you should read events faster and eventually increase the limit for queues. This limit can be read and changed by reading/changing the appropriate procfs file (/proc/sys/fs/inotify/max_queued_events).
Q: What about the IN_ONLYDIR and IN_DONT_FOLLOW flags?
IN_ONLYDIR ensures that the event occur only on a directory. If you create such watch on a file it will not emit events. IN_DONT_FOLLOW forbids following symbolic links (these ones will be monitored themselves and not the files they point to).
Q: My inotify.h doesn't contain IN_ONLYDIR and IN_DONT_FOLLOW values. Can I use them anyway?
Yes, you can, but you must define these symbols manually or use their bitmasks directly. However, these ways are not recommended. The better one is to install a file which already contains these values (see Download).
Q: What is the difference between IN_MODIFY and IN_CLOSE_WRITE?
The IN_MODIFY event is emitted on a file content change (e.g. via the write() syscall) while IN_CLOSE_WRITE occurs on closing the changed file. It means each change operation causes one IN_MODIFY event (it may occur many times during manipulations with an open file) whereas IN_CLOSE_WRITE is emitted only once (on closing the file).
Q: I write to a file using fprintf() and it doesn't emit IN_MODIFY in some cases. Where is the problem?
Library functions like fprintf() use memory buffers and they needn't always accomplish a syscall to do a real writing to a file. If the real write is not called no IN_MODIFY is emitted. You can force the writing e.g. by calling fflush() but it will negatively affect program performance if done often.
Q: Is it better to use IN_MODIFY or IN_CLOSE_WRITE?
It varies from case to case. Usually it is more suitable to use IN_CLOSE_WRITE because if emitted the all changes on the appropriate file are safely written inside the file. The IN_MODIFY event needn't mean that a file change is finished (data may remain in memory buffers in the application). On the other hand, many logs and similar files must be monitored using IN_MODIFY - in such cases where these files are permanently open and thus no IN_CLOSE_WRITE can be emitted.
Q: Why doesn't work IN_MODIFY nor IN_CLOSE_WRITE on my file?
There is probably a program which doesn't save changes directly into the original file. It creates a temporary file instead, saves data into it and after closing it renames the file to the name of the original one. It is safer but complicates monitoring. The exact mechanism of working with files must be investigated (tools like strace can be useful) and the monitoring setup must be tailored to it.
Q: Can I monitor executing a program?
Not directly. You can monitor accessing the executable file (IN_ACCESS) but not distinguish between reading and executing. There is possibility to examine procfs consecutively but it is not reliable.
Q: How to report bugs?
If you think it's really a bug, you can report it through the Kernel Bug Tracker or post it into the Linux Kernel Mailing List.