The name inotify is a contraction of inode notify. Inodes are the names of the filesystem on a Unix system. So files and directories are implemented as inodes in Linux (as well as on macOS since it implements a lot of Unix features). The inotify API is very simple, and is composed of just three functions. These APIs are system calls, accessible via C APIs in the GNU C standard library:

• inotify_init
• inotify_add_watch
• inotify_rm_watch

When an application needs to monitor a directory or a file, it must first create a monitoring context. This is done with the inotify_init function. This function returns a file descriptor. Then, to actually monitor a file, the inotify_add_watch function must be called. This function takes three parameters:

• The file descriptor returned by inotify_init
• The path of the file or directory to monitor
• The list of events to register

The inotify API supports many events, triggered when different conditions occur:

• IN_ACCESS: It is emitted when the file has been read.
• IN_ATTRIB: It is emitted when metadata has changed.
• IN_CLOSE_WRITE: It is emitted when the file has closed and was previously open in write mode.
• IN_CLOSE_NOWRITE: It is emitted when the file has closed and was previously not open in write mode.
• IN_CREATE: It is emitted when a file or a directory has been created. This is only valid when watching directories.
• IN_DELETE: It is emitted when a file or a directory has been deleted. This is only valid when watching directories.
• IN_DELETE_SELF: It is emitted when the file or directory has been deleted.
• IN_MODIFY: It is emitted when the file has changed.
• IN_MOVE_SELF: It is emitted when the file or directory has been moved.
• IN_MOVED_FROM or IN_MOVED_TO: These are emitted when a file has been moved. The first event contains the old name of the file, and the second event contains the new name of the file. This is only valid when watching directories.
• IN_OPEN: It is emitted when the file has been open.

The notification of these events is done with the classical reactor pattern explained in Chapter 1, An Introduction to Reactive Programming. Once the application does not need to monitor the file anymore, it uses the inotify_rm_watch function. The inotify_add_watch function can be called many times with the same inotify file descriptor. This enables the monitoring of several files, with their events being notified via a single file descriptor. When the application does not need the inotify context anymore, it must close the inotify file descriptor to free all the associated resources on the kernel.

The following diagram shows how the inotify API can be used:

The inotify API fits in well in asynchronous and reactive applications for two reasons. First, it is inherently event-based, so chances are that it can be used naturally in existing event-based code. Then, since it is a kernel API working with file descriptors, it is easy to integrate in existing frameworks based on an event loop. And this means that it can integrate nicely in AsyncIO.