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

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

[James Hunt]

[-- 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

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

[Michael Kerrisk (man-pages)]

Hi James,

On Tue, Dec 6, 2011 at 10:40 PM, James Hunt <james.hunt-GeWIH/nMZzLQT0dZR+AlfA@public.gmane.org> wrote:
> man7/inotify.7:
>
> - Explain how to read a single inotify event.
> - Add missing "struct" in explanation of event size.

Re your patch:

> --- 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" .

Applied.

>  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 returnvi
> +.BR EINVAL "."
> +Note that this technique is not particularly efficient.
> +
>  .SH "BUGS"
>  In kernels before 2.6.16, the
>  .B IN_ONESHOT

I've just now added a note to the page that specifying a buffer size
of at least "sizeof(struct inotify_event) + NAME_MAX + 1"  is
sufficient to read *at least* one event. My question is, why do you
want to propose this technique for reading a *single* event.?

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Eric Wong]

"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> My question is, why do you want to propose this technique for reading
> a *single* event.?

It could be useful in multithreaded/multiprocess apps that rely on an
inotify descriptor to distribute work to a thread pool.  accept() and
mq_receive() users do it all the time.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Michael Kerrisk (man-pages)]

Hello Eric,

On Wed, Apr 25, 2012 at 6:11 AM, Eric Wong <normalperson-rMlxZR9MS24@public.gmane.org> wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> My question is, why do you want to propose this technique for reading
>> a *single* event.?
>
> It could be useful in multithreaded/multiprocess apps that rely on an
> inotify descriptor to distribute work to a thread pool.  accept() and
> mq_receive() users do it all the time.

In that case, I'd have thought it more efficient to have a manger
thread read blocks of events and hand them out to members of the pool.
This would be more efficient than performing multiple read() calls.
The difference for accept() and mq_receive() is that they retrieve
single "events" *by definition*.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html