Re: fanotify API: FMODE_NONOTIFY, FMODE_EXEC, FMODE_NOCMTIME

Re: fanotify API: FMODE_NONOTIFY, FMODE_EXEC, FMODE_NOCMTIME

[Michael Kerrisk (man-pages)]

[CC += LKML]

Eric, Jan, (or anyone)

Can you offer any insight on Heinrich's question, below?

Cheers,

Michael

On Sun, Apr 13, 2014 at 4:05 PM, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
> On 06.04.2014 14:18, Michael Kerrisk (man-pages) wrote:
>>>
>>> ==
>>> >
>>> >  >> I notice that the FDs returned by read()s from the FAN FD have the
>>> >  >> FMODE_NONOTIFY flag (fcntl(F_GETFL)) flag set. If you know what
>>> > that's
>>> >  >> about, it would be good to say something about. But, if not, do not
>>> >  >> worry--just place a FIXME in the page source of fanotify(7)
>>> >
>>> >Fixed in fanotify.7
>>> >If the listener accesses the file through the file descriptor provided
>>> >no additional events are created.
>>
>> Ahh -- thanks for filling in that piece. I see that you refer to
>> fcntl(2) when discussing that flag. But fcntl(2) does not
>> mention that flag. I would rather see an explanation of this flag
>> in the fanotify pages.
>>
>
> I wrote a small test program and found:
>
> The flag FMODE_NONOTIFY can be read by function fcntl from userspace.
> int flag = fcntl(fd, F_GETFL)
>
> In include/uapi/asm-generic/fcntl.h I found the following comment:
>
> /*
>  * FMODE_EXEC is 0x20
>  * FMODE_NONOTIFY is 0x1000000
>  * These cannot be used by userspace O_* until internal and external open
>  * flags are split.
>  * -Eric Paris
>  */
>
> The definition of FMODE_NONOTIFY is in include/linux/fs.h but this
> include is only used to compile the Kernel and not supposed to be used by
> userspace.
>
> I think it is quite annoying that fcntl can return a flag that is not
> described in the manpage of fcntl and that is not defined in fcntl.h.
>
> But FMODE_NONOTIFY is not the only flag:
>
> I was able to pass
> 0x20 (FMODE_EXEC), and
> 0x800 (FMODE_NOCMTIME)
> to fanotify_init and received them as flag in the file descriptors for the
> fanotify events.
> I wonder why fanotify_init does not check import parameter event_f_flags and
> return an error if any inappropriate value is set.
>
> Should I put this into the BUGS section?
>
> Should the name of the flag FMODE_NONOTIFY be mentioned at all in the man
> pages?
>
> Or should we write:
>
> .I fd
> This is an open file descriptor for the object being accessed or
> .B FAN_NOFD
> if a queue overflow occurred.
> The file descriptor can be used to access the contents of the monitored file
> or
> directory.
> It has an internal flag set, that suppresses fanotify event generation.
> Hence when the receiver of the fanotify event accesses the notified file or
> directory using this file descriptor no additional events will be created.
> The reading application is responsible for closing the file descriptor.
>
> Best regards
>
> Heinrich Schuchardt



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: fanotify API: FMODE_NONOTIFY, FMODE_EXEC, FMODE_NOCMTIME

[Jan Kara]

  Hello,

On Tue 29-04-14 15:29:12, Michael Kerrisk (man-pages) wrote:
> Can you offer any insight on Heinrich's question, below?
> 
> On Sun, Apr 13, 2014 at 4:05 PM, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
> > On 06.04.2014 14:18, Michael Kerrisk (man-pages) wrote:
> >>>
> >>> ==
> >>> >
> >>> >  >> I notice that the FDs returned by read()s from the FAN FD have the
> >>> >  >> FMODE_NONOTIFY flag (fcntl(F_GETFL)) flag set. If you know what
> >>> > that's
> >>> >  >> about, it would be good to say something about. But, if not, do not
> >>> >  >> worry--just place a FIXME in the page source of fanotify(7)
> >>> >
> >>> >Fixed in fanotify.7
> >>> >If the listener accesses the file through the file descriptor provided
> >>> >no additional events are created.
> >>
> >> Ahh -- thanks for filling in that piece. I see that you refer to
> >> fcntl(2) when discussing that flag. But fcntl(2) does not
> >> mention that flag. I would rather see an explanation of this flag
> >> in the fanotify pages.
> >>
> >
> > I wrote a small test program and found:
> >
> > The flag FMODE_NONOTIFY can be read by function fcntl from userspace.
> > int flag = fcntl(fd, F_GETFL)
> >
> > In include/uapi/asm-generic/fcntl.h I found the following comment:
> >
> > /*
> >  * FMODE_EXEC is 0x20
> >  * FMODE_NONOTIFY is 0x1000000
> >  * These cannot be used by userspace O_* until internal and external open
> >  * flags are split.
> >  * -Eric Paris
> >  */
> >
> > The definition of FMODE_NONOTIFY is in include/linux/fs.h but this
> > include is only used to compile the Kernel and not supposed to be used by
> > userspace.
> >
> > I think it is quite annoying that fcntl can return a flag that is not
> > described in the manpage of fcntl and that is not defined in fcntl.h.
> >
> > But FMODE_NONOTIFY is not the only flag:
> >
> > I was able to pass
> > 0x20 (FMODE_EXEC), and
> > 0x800 (FMODE_NOCMTIME)
> > to fanotify_init and received them as flag in the file descriptors for the
> > fanotify events.
> > I wonder why fanotify_init does not check import parameter event_f_flags and
> > return an error if any inappropriate value is set.
  It seems to me fanotify_init() should really check event_f_flags have
only valid flags set. In particular exclude FMODE_EXEC, FMODE_NOCMTIME, or
FMODE_NONOTIFY.

> > Should I put this into the BUGS section?
> >
> > Should the name of the flag FMODE_NONOTIFY be mentioned at all in the man
> > pages?
> >
> > Or should we write:
> >
> > .I fd
> > This is an open file descriptor for the object being accessed or
> > .B FAN_NOFD
> > if a queue overflow occurred.
> > The file descriptor can be used to access the contents of the monitored file
> > or
> > directory.
> > It has an internal flag set, that suppresses fanotify event generation.
> > Hence when the receiver of the fanotify event accesses the notified file or
> > directory using this file descriptor no additional events will be created.
> > The reading application is responsible for closing the file descriptor.
  So this is what I would prefer. Just mention the file descriptor does not
generate new events. I would even go as far as masking kernel internal
flags like FMODE_EXEC or FMODE_NONOTIFY from the result of F_GETFL. What do
you think Al?

								Honza

-- 
Jan Kara <jack@suse.cz>
SUSE Labs, CR

Re: fanotify API: FMODE_NONOTIFY, FMODE_EXEC, FMODE_NOCMTIME

[Eric Paris]

On Tue, 2014-04-29 at 22:10 +0200, Jan Kara wrote:
>   Hello,
> 
> On Tue 29-04-14 15:29:12, Michael Kerrisk (man-pages) wrote:
> > Can you offer any insight on Heinrich's question, below?
> > 
> > On Sun, Apr 13, 2014 at 4:05 PM, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
> > > On 06.04.2014 14:18, Michael Kerrisk (man-pages) wrote:
> > >>>
> > >>> ==
> > >>> >
> > >>> >  >> I notice that the FDs returned by read()s from the FAN FD have the
> > >>> >  >> FMODE_NONOTIFY flag (fcntl(F_GETFL)) flag set. If you know what
> > >>> > that's
> > >>> >  >> about, it would be good to say something about. But, if not, do not
> > >>> >  >> worry--just place a FIXME in the page source of fanotify(7)
> > >>> >
> > >>> >Fixed in fanotify.7
> > >>> >If the listener accesses the file through the file descriptor provided
> > >>> >no additional events are created.
> > >>
> > >> Ahh -- thanks for filling in that piece. I see that you refer to
> > >> fcntl(2) when discussing that flag. But fcntl(2) does not
> > >> mention that flag. I would rather see an explanation of this flag
> > >> in the fanotify pages.
> > >>
> > >
> > > I wrote a small test program and found:
> > >
> > > The flag FMODE_NONOTIFY can be read by function fcntl from userspace.
> > > int flag = fcntl(fd, F_GETFL)
> > >
> > > In include/uapi/asm-generic/fcntl.h I found the following comment:
> > >
> > > /*
> > >  * FMODE_EXEC is 0x20
> > >  * FMODE_NONOTIFY is 0x1000000
> > >  * These cannot be used by userspace O_* until internal and external open
> > >  * flags are split.
> > >  * -Eric Paris
> > >  */
> > >
> > > The definition of FMODE_NONOTIFY is in include/linux/fs.h but this
> > > include is only used to compile the Kernel and not supposed to be used by
> > > userspace.
> > >
> > > I think it is quite annoying that fcntl can return a flag that is not
> > > described in the manpage of fcntl and that is not defined in fcntl.h.
> > >
> > > But FMODE_NONOTIFY is not the only flag:
> > >
> > > I was able to pass
> > > 0x20 (FMODE_EXEC), and
> > > 0x800 (FMODE_NOCMTIME)
> > > to fanotify_init and received them as flag in the file descriptors for the
> > > fanotify events.
> > > I wonder why fanotify_init does not check import parameter event_f_flags and
> > > return an error if any inappropriate value is set.
>   It seems to me fanotify_init() should really check event_f_flags have
> only valid flags set. In particular exclude FMODE_EXEC, FMODE_NOCMTIME, or
> FMODE_NONOTIFY.

Agreed.  Clearly a bug on my part.

> > > Should I put this into the BUGS section?
> > >
> > > Should the name of the flag FMODE_NONOTIFY be mentioned at all in the man
> > > pages?
> > >
> > > Or should we write:
> > >
> > > .I fd
> > > This is an open file descriptor for the object being accessed or
> > > .B FAN_NOFD
> > > if a queue overflow occurred.
> > > The file descriptor can be used to access the contents of the monitored file
> > > or
> > > directory.
> > > It has an internal flag set, that suppresses fanotify event generation.
> > > Hence when the receiver of the fanotify event accesses the notified file or
> > > directory using this file descriptor no additional events will be created.
> > > The reading application is responsible for closing the file descriptor.
>   So this is what I would prefer. Just mention the file descriptor does not
> generate new events. I would even go as far as masking kernel internal
> flags like FMODE_EXEC or FMODE_NONOTIFY from the result of F_GETFL. What do
> you think Al?

I agree on this point too...