inotify_add_watch()

Add or update a watch for filesystem events associated with a path

Synopsis:

#include <sys/inotify.h>

int inotify_add_watch( int fd,
                       const char *pathname,
                       int mask );

Arguments:

fd
A valid file descriptor returned by inotify_init().
path
The path whose filesystem events you want to monitor.
mask
A bitmask that specifies the events you want to watch. The bits include:
  • IN_ACCESS — the file was read.
  • IN_MODIFY — the file was written to.
  • IN_ATTRIB — the attributes of the file changed.
  • IN_CLOSE_WRITE — a file that was opened for writing was closed.
  • IN_CLOSE_NOWRITE — a file that was opened not for writing was closed.
  • IN_CLOSE — the same as (IN_CLOSE_WRITE | IN_CLOSE_NOWRITE).
  • IN_OPEN — the file was opened.
  • IN_MOVED_FROM — the file was moved or renamed away from the item being watched.
  • IN_MOVED_TO — the file was moved or renamed to the item being watched.
  • IN_MOVE — the same as (IN_MOVED_FROM | IN_MOVED_TO).
  • IN_CREATE — a file was created in a watched directory.
  • IN_DELETE — a file or directory was deleted.
  • IN_DELETE_SELF — the file or directory being monitored was deleted.
  • IN_MOVE_SELF — the file or directory being monitored was moved or renamed.

IN_ALL_EVENTS is a bitwise-OR of all the event types.

You can OR the following into the event type:

  • IN_ONESHOT — remove the watch during the generation of the first event.
  • IN_ONLYDIR — watch the pathname only if it's a directory.
  • IN_DONT_FOLLOW — don't dereference the pathname if it's a symbolic link.
  • IN_EXCL_UNLINK — don't generate events for children after they've been unlinked from the watched directory.
  • IN_MASK_ADD — add events to the watch mask (if one already exists) for this pathname, instead of replacing it.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The inotify_add_watch() function starts watching for filesystem events associated with the given path. To use this function, the filesystem event manager (fsevmgr) manager needs to be running.

For an overview of inotify, see http://www.linuxjournal.com/article/8478?page=0,0 in the Linux Journal, but note that there are differences between the Linux and QNX Neutrino implementations. Currently, only io-blk.so-based filesystems support inotify.

Returns:

A watch descriptor, or -1 if an error occurred (errno is set).

Classification:

Linux

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes