1INOTIFY(7)                 Linux Programmer's Manual                INOTIFY(7)
2
3
4

NAME

6       inotify - monitoring filesystem events
7

DESCRIPTION

9       The  inotify API provides a mechanism for monitoring filesystem events.
10       Inotify can be used to monitor individual files, or to monitor directo‐
11       ries.   When  a  directory is monitored, inotify will return events for
12       the directory itself, and for files inside the directory.
13
14       The following system calls are used with this API:
15
16       *  inotify_init(2) creates an  inotify  instance  and  returns  a  file
17          descriptor  referring to the inotify instance.  The more recent ino‐
18          tify_init1(2) is like inotify_init(2), but has a flags argument that
19          provides access to some extra functionality.
20
21       *  inotify_add_watch(2) manipulates the "watch list" associated with an
22          inotify instance.  Each item ("watch") in the watch  list  specifies
23          the  pathname  of a file or directory, along with some set of events
24          that the kernel should monitor for the  file  referred  to  by  that
25          pathname.   inotify_add_watch(2) either creates a new watch item, or
26          modifies an existing watch.  Each watch has a unique "watch descrip‐
27          tor",  an integer returned by inotify_add_watch(2) when the watch is
28          created.
29
30       *  When events occur for monitored files and directories, those  events
31          are made available to the application as structured data that can be
32          read from the inotify file descriptor using read(2) (see below).
33
34       *  inotify_rm_watch(2) removes an item from an inotify watch list.
35
36       *  When all file descriptors referring to an inotify instance have been
37          closed (using close(2)), the underlying object and its resources are
38          freed for reuse by the kernel; all associated watches are  automati‐
39          cally freed.
40
41       With careful programming, an application can use inotify to efficiently
42       monitor and cache the state of a set of filesystem  objects.   However,
43       robust applications should allow for the fact that bugs in the monitor‐
44       ing logic or races of the kind described  below  may  leave  the  cache
45       inconsistent with the filesystem state.  It is probably wise to do some
46       consistency checking, and rebuild the cache  when  inconsistencies  are
47       detected.
48
49   Reading events from an inotify file descriptor
50       To  determine  what  events have occurred, an application read(2)s from
51       the inotify file descriptor.  If no events have so far occurred,  then,
52       assuming  a blocking file descriptor, read(2) will block until at least
53       one event occurs (unless interrupted by a signal,  in  which  case  the
54       call fails with the error EINTR; see signal(7)).
55
56       Each  successful read(2) returns a buffer containing one or more of the
57       following structures:
58
59           struct inotify_event {
60               int      wd;       /* Watch descriptor */
61               uint32_t mask;     /* Mask describing event */
62               uint32_t cookie;   /* Unique cookie associating related
63                                     events (for rename(2)) */
64               uint32_t len;      /* Size of name field */
65               char     name[];   /* Optional null-terminated name */
66           };
67
68       wd identifies the watch for which this event occurs.  It is one of  the
69       watch descriptors returned by a previous call to inotify_add_watch(2).
70
71       mask contains bits that describe the event that occurred (see below).
72
73       cookie  is  a  unique integer that connects related events.  Currently,
74       this is used only for rename events, and allows the resulting  pair  of
75       IN_MOVED_FROM  and  IN_MOVED_TO  events to be connected by the applica‐
76       tion.  For all other event types, cookie is set to 0.
77
78       The name field is present only when an event is  returned  for  a  file
79       inside  a  watched  directory; it identifies the filename within to the
80       watched directory.  This filename is null-terminated, and  may  include
81       further  null  bytes  ('\0')  to  align  subsequent reads to a suitable
82       address boundary.
83
84       The len field counts all of the  bytes  in  name,  including  the  null
85       bytes; the length of each inotify_event structure is thus sizeof(struct
86       inotify_event)+len.
87
88       The behavior when the buffer given to read(2) is too  small  to  return
89       information about the next event depends on the kernel version: in ker‐
90       nels before 2.6.21, read(2) returns 0;  since  kernel  2.6.21,  read(2)
91       fails with the error EINVAL.  Specifying a buffer of size
92
93           sizeof(struct inotify_event) + NAME_MAX + 1
94
95       will be sufficient to read at least one event.
96
97   inotify events
98       The  inotify_add_watch(2)  mask argument and the mask field of the ino‐
99       tify_event structure returned when read(2)ing an inotify file  descrip‐
100       tor  are both bit masks identifying inotify events.  The following bits
101       can be specified in mask when calling inotify_add_watch(2) and  may  be
102       returned in the mask field returned by read(2):
103
104           IN_ACCESS (+)
105                  File was accessed (e.g., read(2), execve(2)).
106
107           IN_ATTRIB (*)
108                  Metadata  changed—for example, permissions (e.g., chmod(2)),
109                  timestamps (e.g., utimensat(2)), extended attributes  (setx‐
110                  attr(2)), link count (since Linux 2.6.25; e.g., for the tar‐
111                  get of link(2) and for unlink(2)), and user/group ID  (e.g.,
112                  chown(2)).
113
114           IN_CLOSE_WRITE (+)
115                  File opened for writing was closed.
116
117           IN_CLOSE_NOWRITE (*)
118                  File or directory not opened for writing was closed.
119
120           IN_CREATE (+)
121                  File/directory  created  in watched directory (e.g., open(2)
122                  O_CREAT, mkdir(2), link(2), symlink(2), bind(2)  on  a  UNIX
123                  domain socket).
124
125           IN_DELETE (+)
126                  File/directory deleted from watched directory.
127
128           IN_DELETE_SELF
129                  Watched file/directory was itself deleted.  (This event also
130                  occurs if an object is moved to  another  filesystem,  since
131                  mv(1)  in effect copies the file to the other filesystem and
132                  then deletes it from the original filesystem.)  In addition,
133                  an  IN_IGNORED  event will subsequently be generated for the
134                  watch descriptor.
135
136           IN_MODIFY (+)
137                  File was modified (e.g., write(2), truncate(2)).
138
139           IN_MOVE_SELF
140                  Watched file/directory was itself moved.
141
142           IN_MOVED_FROM (+)
143                  Generated for the directory containing the old filename when
144                  a file is renamed.
145
146           IN_MOVED_TO (+)
147                  Generated for the directory containing the new filename when
148                  a file is renamed.
149
150           IN_OPEN (*)
151                  File or directory was opened.
152
153       Inotify monitoring is inode-based: when monitoring a file (but not when
154       monitoring  the directory containing a file), an event can be generated
155       for activity on any link to the file (in the same or a different direc‐
156       tory).
157
158       When monitoring a directory:
159
160       *  the  events marked above with an asterisk (*) can occur both for the
161          directory itself and for objects inside the directory; and
162
163       *  the events marked with a plus sign (+) occur only for objects inside
164          the directory (not for the directory itself).
165
166       Note:  when  monitoring  a  directory, events are not generated for the
167       files inside the directory when the events are performed via a pathname
168       (i.e., a link) that lies outside the monitored directory.
169
170       When  events  are generated for objects inside a watched directory, the
171       name field in the returned inotify_event structure identifies the  name
172       of the file within the directory.
173
174       The  IN_ALL_EVENTS  macro  is defined as a bit mask of all of the above
175       events.  This macro can be used as the mask argument when calling  ino‐
176       tify_add_watch(2).
177
178       Two additional convenience macros are defined:
179
180           IN_MOVE
181                  Equates to IN_MOVED_FROM | IN_MOVED_TO.
182
183           IN_CLOSE
184                  Equates to IN_CLOSE_WRITE | IN_CLOSE_NOWRITE.
185
186       The  following  further bits can be specified in mask when calling ino‐
187       tify_add_watch(2):
188
189           IN_DONT_FOLLOW (since Linux 2.6.15)
190                  Don't dereference pathname if it is a symbolic link.
191
192           IN_EXCL_UNLINK (since Linux 2.6.36)
193                  By default, when watching events on the children of a direc‐
194                  tory, events are generated for children even after they have
195                  been unlinked from the directory.  This can result in  large
196                  numbers of uninteresting events for some applications (e.g.,
197                  if watching /tmp, in which many applications  create  tempo‐
198                  rary  files whose names are immediately unlinked).  Specify‐
199                  ing IN_EXCL_UNLINK changes the  default  behavior,  so  that
200                  events  are  not generated for children after they have been
201                  unlinked from the watched directory.
202
203           IN_MASK_ADD
204                  If a watch instance already exists for the filesystem object
205                  corresponding  to  pathname,  add (OR) the events in mask to
206                  the watch mask (instead of replacing the mask).
207
208           IN_ONESHOT
209                  Monitor the filesystem object corresponding to pathname  for
210                  one event, then remove from watch list.
211
212           IN_ONLYDIR (since Linux 2.6.15)
213                  Watch  pathname  only if it is a directory.  Using this flag
214                  provides an application with a  race-free  way  of  ensuring
215                  that the monitored object is a directory.
216
217       The following bits may be set in the mask field returned by read(2):
218
219           IN_IGNORED
220                  Watch  was removed explicitly (inotify_rm_watch(2)) or auto‐
221                  matically (file was deleted, or filesystem  was  unmounted).
222                  See also BUGS.
223
224           IN_ISDIR
225                  Subject of this event is a directory.
226
227           IN_Q_OVERFLOW
228                  Event queue overflowed (wd is -1 for this event).
229
230           IN_UNMOUNT
231                  Filesystem  containing  watched  object  was  unmounted.  In
232                  addition, an IN_IGNORED event will subsequently be generated
233                  for the watch descriptor.
234
235   Examples
236       Suppose  an  application  is  watching  the  directory dir and the file
237       dir/myfile for all events.  The examples below show  some  events  that
238       will be generated for these two objects.
239
240           fd = open("dir/myfile", O_RDWR);
241                  Generates IN_OPEN events for both dir and dir/myfile.
242
243           read(fd, buf, count);
244                  Generates IN_ACCESS events for both dir and dir/myfile.
245
246           write(fd, buf, count);
247                  Generates IN_MODIFY events for both dir and dir/myfile.
248
249           fchmod(fd, mode);
250                  Generates IN_ATTRIB events for both dir and dir/myfile.
251
252           close(fd);
253                  Generates IN_CLOSE_WRITE events for both dir and dir/myfile.
254
255       Suppose  an  application is watching the directories dir1 and dir2, and
256       the file dir1/myfile.  The following examples show some events that may
257       be generated.
258
259           link("dir1/myfile", "dir2/new");
260                  Generates  an  IN_ATTRIB  event  for myfile and an IN_CREATE
261                  event for dir2.
262
263           rename("dir1/myfile", "dir2/myfile");
264                  Generates an IN_MOVED_FROM event for  dir1,  an  IN_MOVED_TO
265                  event  for  dir2, and an IN_MOVE_SELF event for myfile.  The
266                  IN_MOVED_FROM and IN_MOVED_TO  events  will  have  the  same
267                  cookie value.
268
269       Suppose that dir1/xx and dir2/yy are (the only) links to the same file,
270       and an application is watching dir1, dir2, dir1/xx, and dir2/yy.   Exe‐
271       cuting  the  following calls in the order given below will generate the
272       following events:
273
274           unlink("dir2/yy");
275                  Generates an IN_ATTRIB event for xx (because its link  count
276                  changes) and an IN_DELETE event for dir2.
277
278           unlink("dir1/xx");
279                  Generates  IN_ATTRIB,  IN_DELETE_SELF, and IN_IGNORED events
280                  for xx, and an IN_DELETE event for dir1.
281
282       Suppose an application is watching the directory dir  and  (the  empty)
283       directory dir/subdir.  The following examples show some events that may
284       be generated.
285
286           mkdir("dir/new", mode);
287                  Generates an IN_CREATE | IN_ISDIR event for dir.
288
289           rmdir("dir/subdir");
290                  Generates IN_DELETE_SELF and IN_IGNORED events  for  subdir,
291                  and an IN_DELETE | IN_ISDIR event for dir.
292
293   /proc interfaces
294       The following interfaces can be used to limit the amount of kernel mem‐
295       ory consumed by inotify:
296
297       /proc/sys/fs/inotify/max_queued_events
298              The value in this file is used when an  application  calls  ino‐
299              tify_init(2)  to set an upper limit on the number of events that
300              can be queued to the corresponding inotify instance.  Events  in
301              excess  of this limit are dropped, but an IN_Q_OVERFLOW event is
302              always generated.
303
304       /proc/sys/fs/inotify/max_user_instances
305              This specifies an upper limit on the number of inotify instances
306              that can be created per real user ID.
307
308       /proc/sys/fs/inotify/max_user_watches
309              This  specifies an upper limit on the number of watches that can
310              be created per real user ID.
311

VERSIONS

313       Inotify was merged into the 2.6.13 Linux kernel.  The required  library
314       interfaces  were  added  to  glibc  in  version  2.4.  (IN_DONT_FOLLOW,
315       IN_MASK_ADD, and IN_ONLYDIR were added in glibc version 2.5.)
316

CONFORMING TO

318       The inotify API is Linux-specific.
319

NOTES

321       Inotify file descriptors can be monitored using select(2), poll(2), and
322       epoll(7).  When an event is available, the file descriptor indicates as
323       readable.
324
325       Since Linux 2.6.25, signal-driven I/O  notification  is  available  for
326       inotify  file  descriptors;  see the discussion of F_SETFL (for setting
327       the O_ASYNC flag), F_SETOWN, and F_SETSIG in fcntl(2).   The  siginfo_t
328       structure (described in sigaction(2)) that is passed to the signal han‐
329       dler has the following fields set: si_fd is set  to  the  inotify  file
330       descriptor number; si_signo is set to the signal number; si_code is set
331       to POLL_IN; and POLLIN is set in si_band.
332
333       If successive output  inotify  events  produced  on  the  inotify  file
334       descriptor  are  identical (same wd, mask, cookie, and name), then they
335       are coalesced into a single event if the older event has not  yet  been
336       read (but see BUGS).  This reduces the amount of kernel memory required
337       for the event queue, but also means that an application can't use  ino‐
338       tify to reliably count file events.
339
340       The  events returned by reading from an inotify file descriptor form an
341       ordered queue.  Thus, for example, it is guaranteed that when  renaming
342       from  one  directory to another, events will be produced in the correct
343       order on the inotify file descriptor.
344
345       The set of watch descriptors that is being  monitored  via  an  inotify
346       file  descriptor  can  be  viewed  via  the  entry for the inotify file
347       descriptor in the process's /proc/[pid]/fdinfo directory.  See  proc(5)
348       for further details.  The FIONREAD ioctl(2) returns the number of bytes
349       available to read from an inotify file descriptor.
350
351   Limitations and caveats
352       The inotify API provides no information about the user or process  that
353       triggered the inotify event.  In particular, there is no easy way for a
354       process that is monitoring events via  inotify  to  distinguish  events
355       that  it  triggers  itself  from those that are triggered by other pro‐
356       cesses.
357
358       Inotify reports only events that a user-space program triggers  through
359       the  filesystem API.  As a result, it does not catch remote events that
360       occur on network filesystems.  (Applications must fall back to  polling
361       the  filesystem  to  catch  such events.)  Furthermore, various pseudo-
362       filesystems such as /proc, /sys, and /dev/pts are not monitorable  with
363       inotify.
364
365       The  inotify  API  does not report file accesses and modifications that
366       may occur because of mmap(2), msync(2), and munmap(2).
367
368       The inotify API identifies affected files by filename.  However, by the
369       time  an  application  processes  an  inotify  event,  the filename may
370       already have been deleted or renamed.
371
372       The inotify API identifies events via watch  descriptors.   It  is  the
373       application's  responsibility  to  cache  a  mapping (if one is needed)
374       between watch descriptors  and  pathnames.   Be  aware  that  directory
375       renamings may affect multiple cached pathnames.
376
377       Inotify  monitoring  of directories is not recursive: to monitor subdi‐
378       rectories under a directory, additional watches must be created.   This
379       can take a significant amount time for large directory trees.
380
381       If  monitoring  an  entire directory subtree, and a new subdirectory is
382       created in that tree or an existing  directory  is  renamed  into  that
383       tree,  be  aware that by the time you create a watch for the new subdi‐
384       rectory, new files (and subdirectories) may already  exist  inside  the
385       subdirectory.  Therefore, you may want to scan the contents of the sub‐
386       directory immediately after adding the watch (and, if  desired,  recur‐
387       sively add watches for any subdirectories that it contains).
388
389       Note that the event queue can overflow.  In this case, events are lost.
390       Robust applications should handle the possibility of lost events grace‐
391       fully.   For example, it may be necessary to rebuild part or all of the
392       application cache.  (One simple, but possibly expensive, approach is to
393       close  the  inotify file descriptor, empty the cache, create a new ino‐
394       tify file descriptor, and then re-create watches and cache entries  for
395       the objects to be monitored.)
396
397       If a filesystem is mounted on top of a monitored directory, no event is
398       generated, and no events are generated for  objects  immediately  under
399       the  new  mount  point.   If  the filesystem is subsequently unmounted,
400       events will subsequently be generated for the directory and the objects
401       it contains.
402
403   Dealing with rename() events
404       As  noted  above,  the IN_MOVED_FROM and IN_MOVED_TO event pair that is
405       generated by rename(2) can be matched up via their shared cookie value.
406       However, the task of matching has some challenges.
407
408       These  two events are usually consecutive in the event stream available
409       when reading from the inotify file descriptor.  However,  this  is  not
410       guaranteed.   If multiple processes are triggering events for monitored
411       objects, then (on rare occasions) an arbitrary number of  other  events
412       may  appear between the IN_MOVED_FROM and IN_MOVED_TO events.  Further‐
413       more, it is not guaranteed that the event pair is  atomically  inserted
414       into  the  queue: there may be a brief interval where the IN_MOVED_FROM
415       has appeared, but the IN_MOVED_TO has not.
416
417       Matching up the IN_MOVED_FROM and IN_MOVED_TO event pair  generated  by
418       rename(2)  is thus inherently racy.  (Don't forget that if an object is
419       renamed outside of a monitored directory, there  may  not  even  be  an
420       IN_MOVED_TO  event.)  Heuristic approaches (e.g., assume the events are
421       always consecutive) can be used to ensure a match in  most  cases,  but
422       will  inevitably  miss  some cases, causing the application to perceive
423       the IN_MOVED_FROM and IN_MOVED_TO events as being unrelated.  If  watch
424       descriptors  are destroyed and re-created as a result, then those watch
425       descriptors will be inconsistent with  the  watch  descriptors  in  any
426       pending  events.  (Re-creating the inotify file descriptor and rebuild‐
427       ing the cache may be useful to deal with this scenario.)
428
429       Applications  should  also  allow  for   the   possibility   that   the
430       IN_MOVED_FROM  event  was  the  last event that could fit in the buffer
431       returned  by  the  current  call  to  read(2),  and  the   accompanying
432       IN_MOVED_TO  event  might  be  fetched  only on the next read(2), which
433       should be done with a (small) timeout to allow for the fact that inser‐
434       tion  of  the  IN_MOVED_FROM-IN_MOVED_TO  event pair is not atomic, and
435       also the possibility that there may not be any IN_MOVED_TO event.
436

BUGS

438       Before Linux 3.19, fallocate(2) did  not  create  any  inotify  events.
439       Since Linux 3.19, calls to fallocate(2) generate IN_MODIFY events.
440
441       In kernels before 2.6.16, the IN_ONESHOT mask flag does not work.
442
443       As  originally  designed  and  implemented, the IN_ONESHOT flag did not
444       cause an IN_IGNORED event to be generated when the  watch  was  dropped
445       after  one  event.   However, as an unintended effect of other changes,
446       since Linux 2.6.36, an IN_IGNORED event is generated in this case.
447
448       Before kernel 2.6.25, the kernel code that  was  intended  to  coalesce
449       successive  identical  events  (i.e.,  the two most recent events could
450       potentially be coalesced if the older had not yet  been  read)  instead
451       checked  if  the  most  recent event could be coalesced with the oldest
452       unread event.
453
454       When a watch descriptor is removed by calling  inotify_rm_watch(2)  (or
455       because  a  watch file is deleted or the filesystem that contains it is
456       unmounted), any pending unread events for that watch descriptor  remain
457       available  to  read.   As  watch descriptors are subsequently allocated
458       with inotify_add_watch(2), the kernel cycles through the range of  pos‐
459       sible  watch descriptors (0 to INT_MAX) incrementally.  When allocating
460       a free watch descriptor, no check is made to  see  whether  that  watch
461       descriptor  number  has any pending unread events in the inotify queue.
462       Thus, it can happen that a watch descriptor is  reallocated  even  when
463       pending  unread  events  exist for a previous incarnation of that watch
464       descriptor number, with the result that the application might then read
465       those  events  and  interpret  them as belonging to the file associated
466       with the newly recycled watch descriptor.  In practice, the  likelihood
467       of  hitting  this  bug  may be extremely low, since it requires that an
468       application cycle through INT_MAX watch descriptors,  release  a  watch
469       descriptor while leaving unread events for that watch descriptor in the
470       queue, and then recycle that watch descriptor.  For  this  reason,  and
471       because  there  have been no reports of the bug occurring in real-world
472       applications, as of Linux 3.15, no kernel changes have yet been made to
473       eliminate this possible bug.
474

EXAMPLE

476       The  following  program  demonstrates the usage of the inotify API.  It
477       marks the directories passed as a command-line arguments and waits  for
478       events of type IN_OPEN, IN_CLOSE_NOWRITE and IN_CLOSE_WRITE.
479
480       The   following   output   was   recorded   while   editing   the  file
481       /home/user/temp/foo and listing directory /tmp.  Before  the  file  and
482       the directory were opened, IN_OPEN events occurred.  After the file was
483       closed, an IN_CLOSE_WRITE event  occurred.   After  the  directory  was
484       closed,  an  IN_CLOSE_NOWRITE event occurred.  Execution of the program
485       ended when the user pressed the ENTER key.
486
487   Example output
488           $ ./a.out /tmp /home/user/temp
489           Press enter key to terminate.
490           Listening for events.
491           IN_OPEN: /home/user/temp/foo [file]
492           IN_CLOSE_WRITE: /home/user/temp/foo [file]
493           IN_OPEN: /tmp/ [directory]
494           IN_CLOSE_NOWRITE: /tmp/ [directory]
495
496           Listening for events stopped.
497
498   Program source
499
500       #include <errno.h>
501       #include <poll.h>
502       #include <stdio.h>
503       #include <stdlib.h>
504       #include <sys/inotify.h>
505       #include <unistd.h>
506
507       /* Read all available inotify events from the file descriptor 'fd'.
508          wd is the table of watch descriptors for the directories in argv.
509          argc is the length of wd and argv.
510          argv is the list of watched directories.
511          Entry 0 of wd and argv is unused. */
512
513       static void
514       handle_events(int fd, int *wd, int argc, char* argv[])
515       {
516           /* Some systems cannot read integer variables if they are not
517              properly aligned. On other systems, incorrect alignment may
518              decrease performance. Hence, the buffer used for reading from
519              the inotify file descriptor should have the same alignment as
520              struct inotify_event. */
521
522           char buf[4096]
523               __attribute__ ((aligned(__alignof__(struct inotify_event))));
524           const struct inotify_event *event;
525           int i;
526           ssize_t len;
527           char *ptr;
528
529           /* Loop while events can be read from inotify file descriptor. */
530
531           for (;;) {
532
533               /* Read some events. */
534
535               len = read(fd, buf, sizeof buf);
536               if (len == -1 && errno != EAGAIN) {
537                   perror("read");
538                   exit(EXIT_FAILURE);
539               }
540
541               /* If the nonblocking read() found no events to read, then
542                  it returns -1 with errno set to EAGAIN. In that case,
543                  we exit the loop. */
544
545               if (len <= 0)
546                   break;
547
548               /* Loop over all events in the buffer */
549
550               for (ptr = buf; ptr < buf + len;
551                       ptr += sizeof(struct inotify_event) + event->len) {
552
553                   event = (const struct inotify_event *) ptr;
554
555                   /* Print event type */
556
557                   if (event->mask & IN_OPEN)
558                       printf("IN_OPEN: ");
559                   if (event->mask & IN_CLOSE_NOWRITE)
560                       printf("IN_CLOSE_NOWRITE: ");
561                   if (event->mask & IN_CLOSE_WRITE)
562                       printf("IN_CLOSE_WRITE: ");
563
564                   /* Print the name of the watched directory */
565
566                   for (i = 1; i < argc; ++i) {
567                       if (wd[i] == event->wd) {
568                           printf("%s/", argv[i]);
569                           break;
570                       }
571                   }
572
573                   /* Print the name of the file */
574
575                   if (event->len)
576                       printf("%s", event->name);
577
578                   /* Print type of filesystem object */
579
580                   if (event->mask & IN_ISDIR)
581                       printf(" [directory]\n");
582                   else
583                       printf(" [file]\n");
584               }
585           }
586       }
587
588       int
589       main(int argc, char* argv[])
590       {
591           char buf;
592           int fd, i, poll_num;
593           int *wd;
594           nfds_t nfds;
595           struct pollfd fds[2];
596
597           if (argc < 2) {
598               printf("Usage: %s PATH [PATH ...]\n", argv[0]);
599               exit(EXIT_FAILURE);
600           }
601
602           printf("Press ENTER key to terminate.\n");
603
604           /* Create the file descriptor for accessing the inotify API */
605
606           fd = inotify_init1(IN_NONBLOCK);
607           if (fd == -1) {
608               perror("inotify_init1");
609               exit(EXIT_FAILURE);
610           }
611
612           /* Allocate memory for watch descriptors */
613
614           wd = calloc(argc, sizeof(int));
615           if (wd == NULL) {
616               perror("calloc");
617               exit(EXIT_FAILURE);
618           }
619
620           /* Mark directories for events
621              - file was opened
622              - file was closed */
623
624           for (i = 1; i < argc; i++) {
625               wd[i] = inotify_add_watch(fd, argv[i],
626                                         IN_OPEN | IN_CLOSE);
627               if (wd[i] == -1) {
628                   fprintf(stderr, "Cannot watch '%s'\n", argv[i]);
629                   perror("inotify_add_watch");
630                   exit(EXIT_FAILURE);
631               }
632           }
633
634           /* Prepare for polling */
635
636           nfds = 2;
637
638           /* Console input */
639
640           fds[0].fd = STDIN_FILENO;
641           fds[0].events = POLLIN;
642
643           /* Inotify input */
644
645           fds[1].fd = fd;
646           fds[1].events = POLLIN;
647
648           /* Wait for events and/or terminal input */
649
650           printf("Listening for events.\n");
651           while (1) {
652               poll_num = poll(fds, nfds, -1);
653               if (poll_num == -1) {
654                   if (errno == EINTR)
655                       continue;
656                   perror("poll");
657                   exit(EXIT_FAILURE);
658               }
659
660               if (poll_num > 0) {
661
662                   if (fds[0].revents & POLLIN) {
663
664                       /* Console input is available. Empty stdin and quit */
665
666                       while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\n')
667                           continue;
668                       break;
669                   }
670
671                   if (fds[1].revents & POLLIN) {
672
673                       /* Inotify events are available */
674
675                       handle_events(fd, wd, argc, argv);
676                   }
677               }
678           }
679
680           printf("Listening for events stopped.\n");
681
682           /* Close inotify file descriptor */
683
684           close(fd);
685
686           free(wd);
687           exit(EXIT_SUCCESS);
688       }
689

SEE ALSO

691       inotifywait(1), inotifywatch(1), inotify_add_watch(2), inotify_init(2),
692       inotify_init1(2), inotify_rm_watch(2), read(2), stat(2), fanotify(7)
693
694       Documentation/filesystems/inotify.txt in the Linux kernel source tree
695

COLOPHON

697       This  page  is  part of release 4.16 of the Linux man-pages project.  A
698       description of the project, information about reporting bugs,  and  the
699       latest     version     of     this    page,    can    be    found    at
700       https://www.kernel.org/doc/man-pages/.
701
702
703
704Linux                             2017-09-15                        INOTIFY(7)
Impressum