Explain bug that occurred in coalescing identical events in

kernels before 2.6.25.
(See commit 1c17d18e3775485bf1e0ce79575eb637a94494a2
"A potential bug in inotify_user.c" in the 2.6.25 Changelog.)

man7/inotify.7

@@ -23,7 +23,7 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.TH INOTIFY 7 2008-05-15 "Linux" "Linux Programmer's Manual"
+.TH INOTIFY 7 2008-08-27 "Linux" "Linux Programmer's Manual"
 .SH NAME
 inotify \- monitoring file system events
 .SH DESCRIPTION
@@ -352,7 +352,8 @@ inotify file descriptor are identical (same
 .IR cookie ,
 and
 .IR name )
-then they are coalesced into a single event.
+then they are coalesced into a single event if the
+older event has not yet been read (but see BUGS).
 
 The events returned by reading from an inotify file descriptor
 form an ordered queue.
@@ -374,6 +375,15 @@ In kernels before 2.6.16, the
 .B IN_ONESHOT
 .I mask
 flag does not work.
+
+Before kernel 2.6.25,
+a kernel bug meant that the kernel code that was intended
+to coalesce successive identical events
+(i.e., the two most recent events could potentially be coalesced
+if the older had not yet been read)
+instead checked if the most recent event could be coalesced with the
+.I oldest
+unread event.
 .SH "SEE ALSO"
 .BR inotify_add_watch (2),
 .BR inotify_init (2),