[PATCH] Explain how to read a single inotify event.

[James Hunt <james.hunt-GeWIH/nMZzLQT0dZR+AlfA@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 147 bytes --]

man7/inotify.7:

- Explain how to read a single inotify event.
- Add missing "struct" in explanation of event size.

Kind regards,
-- 
James Hunt


[-- Attachment #2: 0001-Explain-how-to-read-a-single-inotify-event.patch --]
[-- Type: text/x-diff, Size: 1787 bytes --]

>From 2c2e9150661fc12142725f97e3cebf8ff64e1264 Mon Sep 17 00:00:00 2001
From: James Hunt <james.hunt-GeWIH/nMZzLQT0dZR+AlfA@public.gmane.org>
Date: Tue, 6 Dec 2011 09:33:51 +0000
Subject: Explain how to read a single inotify event.

Also added missing "struct" to sizeof().
---
 man7/inotify.7 |   24 +++++++++++++++++++++++-
 1 files changed, 23 insertions(+), 1 deletions(-)

diff --git a/man7/inotify.7 b/man7/inotify.7
index ddeb5e5..742dec2 100644
--- a/man7/inotify.7
+++ b/man7/inotify.7
@@ -144,7 +144,7 @@ including the null bytes;
 the length of each
 .I inotify_event
 structure is thus
-.IR "sizeof(inotify_event)+len" .
+.IR "sizeof(struct inotify_event)+len" .
 
 The behavior when the buffer given to
 .BR read (2)
@@ -417,6 +417,28 @@ be aware that by the time you create a watch for the new subdirectory,
 new files may already have been created in the subdirectory.
 Therefore, you may want to scan the contents of the subdirectory
 immediately after adding the watch.
+
+To read a
+.B single
+event requires the buffer provided to
+.BR read (2)
+be large enough to hold the event. However, since inotify employs
+variable-length events for files in a watched directory (via the
+.I name
+field), it is not possible to know exactly how big such a
+buffer should be since the event itself has not yet been read. One
+method to overcome this limitation is to start with a buffer of size
+.I sizeof(struct inotify_event)
+and attempt to read the event. If this fails with
+.BR EINVAL ","
+continue to increase the buffer size by one byte up to
+.I "sizeof(struct inotify_event)+NAME_MAX"
+until
+.BR read (2)
+does not return
+.BR EINVAL "."
+Note that this technique is not particularly efficient.
+
 .SH "BUGS"
 In kernels before 2.6.16, the
 .B IN_ONESHOT
-- 
1.7.5.4