How to Use inotify API in C Language

Inotify is a Linux API used for file system events monitoring.

This article will show you how Inotify is used for tracking the creation, deletion, or modification of files and directories of the Linux file system.

To monitor a specific file or directory using Inotify, follow these steps:

1. Create an inotify instance using the inotify_init()
2. Add the full path of the directory or the file to monitor and the events to watch using the function inotify_add_watch(). In the same function, we specify which events (ON CREATE, ON ACCESS, ON MODIFY etc.), changes to the files, or changes to the directory must be monitored.
3. Wait for events to occur and read the buffer, which contains one or more events that occurred, using the read() or select()
4. Process the event which has occurred, then return to step 3 to wait for more events, and repeat.
5. Remove the watch descriptor using the inotify_rm_watch()
6. Close the inotify instance.

Now, we will see the functions that are used for Inotify API.

Header file: sys/inotify.h

inotify_init() function :

Syntax: int inotify_init (void)

Arguments: No arguments.

Return Values: On success, the function returns a new file descriptor, for failure the function returns -1.

inotify_add_watch() function:

Syntax: int inotify_add_watch ( int fd, const char *pathname, uint32_t mask )

Arguments:

This function takes three arguments.

The 1^st argument (fd) is a file descriptor which refer to the inotify instance (return value of inotify_init() function) .

The 2^nd argument is path of the directory or file which is being monitored.

The 3^rd argument is a bitmask. The bitmask represents the events which are being watched. We can watch one or more events using bitwise-OR.

Return Values: On success, the function returns a watch descriptor, for failure the function returns -1.

inotify_rm_watch() function:

Syntax: int inotify_rm_watch ( int fd, int32_t wd )

Arguments:

This function takes two arguments.

The 1^st argument (fd) is a file descriptor which refer to the inotify instance (return value of inotify_init() function) .

The 2^nd argument (wd) is a watch descriptor (return value of inotify_add_watch()  function) .

Return Values:  On success, the function returns 0, for failure the function returns -1.

We use read() function(declared in unistd.h header file) to read the buffer, which is stored the information of the events occurred in the form of the inotify_event structure. The inotify_event structure is declared in sys/inotify.h header file:

The inotify_event structure represents a file system event returned by the inotify system and contains the following members:

• wd: Watch descriptor (return value of inotify_add_watch() function)
• mask: A bit mask that includes all the event types
• cookie: Unique number that identifies events
• len: Number of bytes in the name field
• name: Name of the file or directory in which the event occurred

Below is a working example, using the Inotify API:

Inotify.c file:

Output:

To execute the program and see the output, we must first open two terminals. One terminal is used to run the program Inotify.c. In the second terminal, we go to the path that is being watched by the Inotify.c. If we create any directory or file, modify any file, or delete any directory or file, we will see these on the first terminal.

In the Inotify.c example, the unistd.h header file is used for the read() and close() function, the stdlib.h header file is used for the exit() function, the signal.h header file is used for the signal() function and the SIG_INT macro (See signal handling for details), and the fcntl.h header file is used for the fcntl() function.

We declare fd (inotify instance) and wd (watch descriptor) as global variables so that these variables are accessible from all functions.

The fcntl() function is used so that when we read using the fd descriptor, the thread will not be blocked.

Next, we add a watch using the inotify_add_watch() function. Here, we pass fd, the path of the directory that will be watched, and the mask. You can pass the mask of the events you want to monitor using bitwise-OR.

Now, read the buffer. Information about one or more events is stored in the buffer. You can process all events one by one using the loop. You may check the event->mask to know which type of events have happened.

We use an infinite while loop to continuously check when events occurred. If no events have happened, the read() function returns with a  0. The return value of the read() function is stored in the length variable. When the value of the length variable is greater than zero, one or more events have occurred.

We use the SIG_INT signal (press Ctrl C) to exit from the process. When you press Ctrl C, the sig_handler() function is called (See signal handling for details). This function removes the watch descriptor, closes the inotify instance fd, and exits the program.

Conclusion

You can use Inotify API in your own applications for monitoring, debugging, automation, and more, in your own way. Here, we have seen the execution flow of Inotify API.