Function: inotify-add-watch

inotify-add-watch is a function defined in inotify.c.

Signature

(inotify-add-watch FILENAME ASPECT CALLBACK)

Documentation

Add a watch for FILE-NAME to inotify.

Return a watch descriptor. The watch will look for ASPECT events and invoke CALLBACK when an event occurs.

ASPECT might be one of the following symbols or a list of those symbols:

access attrib close-write close-nowrite create delete delete-self modify move-self moved-from moved-to open

all-events or t move close

ASPECT can also contain the following symbols, which control whether the watch descriptor will be created:

dont-follow onlydir

Watching a directory is not recursive. CALLBACK is passed a single argument EVENT which contains an event structure of the format

(WATCH-DESCRIPTOR ASPECTS NAME COOKIE)

WATCH-DESCRIPTOR is the same object that was returned by this function. It can be tested for equality using equal. ASPECTS describes the event. It is a list of ASPECT symbols described above and can also contain one of the following symbols

ignored isdir q-overflow unmount

If a directory is watched then NAME is the name of file that caused the event.

COOKIE is an object that can be compared using equal to identify two matching renames (moved-from and moved-to).

See inotify(7) and inotify_add_watch(2) for further information. The inotify fd is managed internally and there is no corresponding inotify_init. Use inotify-rm-watch to remove a watch.

The following inotify bit-masks cannot be used because descriptors are shared across different callers.

IN_EXCL_UNLINK IN_MASK_ADD IN_ONESHOT

Source Code

// Defined in /usr/src/emacs/src/inotify.c
{
  Lisp_Object encoded_file_name;
  int wd = -1;
  uint32_t imask = aspect_to_inotifymask (aspect);
  uint32_t mask = imask | IN_MASK_ADD | IN_EXCL_UNLINK;

  CHECK_STRING (filename);

  if (inotifyfd < 0)
    {
      inotifyfd = inotify_init1 (IN_NONBLOCK | IN_CLOEXEC);
      if (inotifyfd < 0)
	report_file_notify_error ("File watching is not available", Qnil);
      watch_list = Qnil;
      add_read_fd (inotifyfd, &inotify_callback, NULL);
    }

  encoded_file_name = ENCODE_FILE (filename);
  wd = inotify_add_watch (inotifyfd, SSDATA (encoded_file_name), mask);
  if (wd < 0)
    report_file_notify_error ("Could not add watch for file", filename);

  return add_watch (wd, filename, imask, callback);
}