Bug 198569 - fanotify_mark(2): wrong info about allowed bits in mask
Summary: fanotify_mark(2): wrong info about allowed bits in mask
Status: RESOLVED CODE_FIX
Alias: None
Product: Documentation
Classification: Unclassified
Component: man-pages (show other bugs)
Hardware: All Linux
: P1 normal
Assignee: documentation_man-pages@kernel-bugs.osdl.org
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2018-01-23 23:27 UTC by Alexander Morozov
Modified: 2020-04-23 12:44 UTC (History)
2 users (show)

See Also:
Kernel Version:
Subsystem:
Regression: No
Bisected commit-id:


Attachments

Description Alexander Morozov 2018-01-23 23:27:41 UTC
man fanotify_mark tells that mask argument can include FAN_Q_OVERFLOW but the function returns EINVAL if it is used.
Comment 1 Michael Kerrisk 2020-04-23 10:25:51 UTC
I tested and confirmed what you see (by taking the first example program in fanotify(7) and adding FAN_Q_OVERFLOW to the mask argument).

Looking at the checks in the kernel code seems to provide further confirmation, since in do_fanotify_mark() we have:

        if (mask & ~valid_mask)
                return -EINVAL;

where:

        u32 valid_mask = FANOTIFY_EVENTS | FANOTIFY_EVENT_FLAGS;

and:

#define FANOTIFY_EVENTS         (FANOTIFY_PATH_EVENTS | \
                                 FANOTIFY_INODE_EVENTS)

#define FANOTIFY_PATH_EVENTS    (FAN_ACCESS | FAN_MODIFY | \
                                 FAN_CLOSE | FAN_OPEN | FAN_OPEN_EXEC)
#define FANOTIFY_INODE_EVENTS   (FANOTIFY_DIRENT_EVENTS | \
                                 FAN_ATTRIB | FAN_MOVE_SELF | FAN_DELETE_SELF)

#define FANOTIFY_EVENT_FLAGS    (FAN_EVENT_ON_CHILD | FAN_ONDIR)

None of the above includes FAN_Q_OVERFLOW.

Furthermore, there is:

/* Events that may be reported to user */
#define FANOTIFY_OUTGOING_EVENTS        (FANOTIFY_EVENTS | \
                                         FANOTIFY_PERM_EVENTS | \
                                         FAN_Q_OVERFLOW | FAN_ONDIR)

Since that definition includes both FAN_Q_OVERFLOW and FANOTIFY_EVENTS, that seems further confirmation that FAN_Q_OVERFLOW is an output value, not an input value.

The only thing that bothers me is that the person who added that text to the manual page is normally fairly careful. I'll check with him.
Comment 2 Michael Kerrisk 2020-04-23 12:44:06 UTC
See https://lore.kernel.org/linux-man/CAKgNAki3BwX3_oSQ158T=6+5uRwsBKrNkz=aaF-2_d933PZCBA@mail.gmail.com/T/#t

I applied the patch below.

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 5efab6a57..6ca038a57 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -276,13 +276,6 @@ An fanotify file descriptor created with
 .BR FAN_REPORT_FID
 is required.
 .TP
-.B FAN_Q_OVERFLOW
-Create an event when an overflow of the event queue occurs.
-The size of the event queue is limited to 16384 entries if
-.B FAN_UNLIMITED_QUEUE
-is not set in
-.BR fanotify_init (2).
-.TP
 .B FAN_OPEN_PERM
 Create an event when a permission to open a file or directory is requested.
 An fanotify file descriptor created with

Note You need to log in before you can comment on or make changes to this bug.