fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and Directory entry events
RFC PATCH 1/1 fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
In reply to Matthew BobrowskiDetails relating to the new API initialization flag FAN_REPORT_FID has been added. As part of the FAN_REPORT_FID feature, a new set of event masks are available and have been documented accordingly.
A simple example program has been added to also support the understanding and use case of FAN_REPORT_FID and directory events.
--- man2/fanotify_init.2 | 29 ++++ man2/fanotify_mark.2 | 93 ++++++++++++- man7/fanotify.7 | 313 +++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 425 insertions(+), 10 deletions(-)
man2/fanotify_init.2 +29 -0
@@ -94,6 +94,33 @@ already contain their final content. This notification class might be used by malware detection programs, for example. .TP +.B FAN_REPORT_FID +This value allows the receipt of events which contain additional information +about the underlying object correlated to an event. +An additional structure encapsulates the information about the object and is +included alongside the generic event metadata structure. +The file descriptor that is used to represent the object correlated to an +event is instead substituted with a file handle. +It is intended for applications that may find the use of a file handle to +identify an object more suitable than a file descriptor. +Additionally, it may be used for applications that are interested in +directory entry events, such as +.BR FAN_CREATE , +.BR FAN_ATTRIB , +.BR FAN_MOVE +and +.BR FAN_DELETE +for example. +The use of +.BR FAN_CLASS_CONTENT +or +.BR FAN_CLASS_PRE_CONTENT +is not permitted with this flag and will result in the error +.BR EINVAL . +See +.BR fanotify (7) +for additional information. +.TP .B FAN_CLASS_NOTIF This is the default value. It does not need to be specified.
@@ -224,6 +251,8 @@ An invalid value was passed in or .IR event_f_flags . .B FAN_ALL_INIT_FLAGS +(deprecated since Linux kernel version 4.20) +.\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4 defines all allowable bits for .IR flags . .TP
man2/fanotify_mark.2 +91 -2
139 lines not on this page · raw message
man7/fanotify.7 +305 -8
380 lines not on this page · raw message
Signature · 5 lines
2.17.2 -- Matthew Bobrowski
cover fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and Directory entry events
This patch contains the updates needed to support the new FAN_REPORT_FID flag and directory entry modification events.
This is a new fanoitfy API feature that has been recently merged into upstream master so looking to get some early feedback on the documentation side of things.
Matthew Bobrowski (1):
fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID
and directory modification events
man2/fanotify_init.2 | 29 ++++ man2/fanotify_mark.2 | 93 ++++++++++++- man7/fanotify.7 | 313 +++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 425 insertions(+), 10 deletions(-)
Signature · 5 lines
2.17.2 -- Matthew Bobrowski
Jan Kara
reviewerRe: [RFC PATCH 1/1] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
In reply to Matthew BobrowskiThanks for the manpage updates! Some small comments below.
man2/fanotify_mark.2 Create an event when a file or directory is opened. · line 201
Quoted 8 lines · Matthew Bobrowski
+.TP
+.BFAN_MOVED_FROMman2/fanotify_mark.2 +6
-0+Create an event when a marked file or directory is moved from the current +location. +.TP +.B FAN_MOVED_TO +Create an event when a marked file or directory is moved to a new +location.
For these two events (like other directory events), marked thing is actually again the parent directory - i.e., these events trigger is something is moved to / from marked directory. So I think it would be clearer and use the same language like e.g. for FAN_CREATE and speak about marked parent directory.
man2/fanotify_mark.2 or · line 254
Quoted 12 lines
Without this flag, only events for files are created.
man2/fanotify_mark.2 +11
-0+The +.BR FAN_ONDIR +flag is reported in an event mask only if the +.I fanotify_fd +file descriptor has been initialized with the flag +.BR FAN_REPORT_FID . +In the context of directory entry events, such as +.BR FAN_CREATE , +.BR FAN_DELETE +and +.BR FAN_MOVE
Maybe too early to speak about FAN_MOVE here as it's not defined yet? I'd rather explicitely use FAN_MOVE_FROM and FAN_MOVE_TO here.
Quoted 4 lines
man7/fanotify.7 +0
-0
...
Quoted 7 lines
+.B
FAN_ATTRIBman7/fanotify.7 +6
-0+A file or directory metadata was changed. +.TP +.B FAN_CREATE +A child file or directory was created in a watched parent. +.TP +.B FAN_DELETE
man7/fanotify.7 See NOTES in · line 315
Quoted 10 lines
man7/fanotify.7 +10
-0+A child file or directory was deleted in a watched parent. +.TP +.B FAN_DELETE_SELF +A watched file or directory was deleted. +.TP +.B FAN_MOVED_FROM +A watched file or directory was moved from the current location. +.TP +.B FAN_MOVED_TO +A watched file or directory was moved to a new location.
The same comment here about parent directory being actually marked.
man7/fanotify.7 This is a synonym for: · line 388
Quoted 6 lines
+.TP
+.I hdrman7/fanotify.7 +4
-0+This is a structure of type +.IR fanotify_event_info_header . +It is a generic header that contains information used to describe the type +of event.
"type of event" seems a bit unfortunate wording here since I'd expect that to be FAN_CREATE or whatever. I'd rather choose something like "used to describe additional information attached to the event".
man7/fanotify.7 This is a synonym for: · line 396
Quoted 8 lines
man7/fanotify.7 +8
-0+For example, when an fanotify file descriptor is created using +.B FAN_REPORT_FID +the +.I info_type +field of this header is set to +.BR FAN_EVENT_INFO_TYPE_FID . +Event listeners can use this field to check that events of the correct +type are being received.
I think here you should also speak about the 'len' field in the header which can be used to skip additional information that is not understood / uninteresting for the receiver of the event.
Quoted 7 lines
+.TP
+.I fsidman7/fanotify.7 +5
-0+This is a unique identifier of the filesystem containing the object +associated with the event. +It is a structure of type +.I __kernel_fsid_t +and contains the same value as
man7/fanotify.7 This is a synonym for: · line 413
Quoted 10 lines
man7/fanotify.7 +10
-0+.I f_fsid +when calling +.BR statfs (2). +.TP +.I file_handle +This is a variable length structure of type +.IR file_handle . +It is an opaque handle that corresponds to a specified object on a +filesystem as returned by +.BR name_at_handle_at (2) .
name_to_handle_at (2)
man7/fanotify.7 After the file was closed, a · line 716
Quoted 12 lines
+.PP
man7/fanotify.7 +11
-0+The second example program output was captured from fanotify_fid. +There are two discrete invocations to this program with each invocation +accommodating a different action performed on a watched object. +This first session shows a mark being placed on +.IR /home/user . +This is followed by a subsequent regular file +.IR /home/user/testfile.txt +being created. +This results in a +.B FAN_CREATE +event being created and reported against the files parent watched
^^^ file's ? Honza
Signature · 2 lines
Jan Kara <[email protected]> SUSE Labs, CR
Re: [RFC PATCH 1/1] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
Quoted 71 lines · Jan Kara
Thanks for the manpage updates! Some small comments below.
man2/fanotify_mark.2 Create an event when a file or directory is opened. · line 201
Quoted 8 lines · Matthew Bobrowski
+.TP
+.BFAN_MOVED_FROMman2/fanotify_mark.2 +6
-0+Create an event when a marked file or directory is moved from the current +location. +.TP +.B FAN_MOVED_TO +Create an event when a marked file or directory is moved to a new +location.For these two events (like other directory events), marked thing is actually again the parent directory - i.e., these events trigger is something is moved to / from marked directory. So I think it would be clearer and use the same language like e.g. for
FAN_CREATEand speak about marked parent directory.man2/fanotify_mark.2 or · line 254
Quoted 12 lines
Without this flag, only events for files are created.
man2/fanotify_mark.2 +11
-0+The +.BR FAN_ONDIR +flag is reported in an event mask only if the +.I fanotify_fd +file descriptor has been initialized with the flag +.BR FAN_REPORT_FID . +In the context of directory entry events, such as +.BR FAN_CREATE , +.BR FAN_DELETE +and +.BR FAN_MOVEMaybe too early to speak about
FAN_MOVEhere as it's not defined yet? I'd rather explicitely useFAN_MOVE_FROMandFAN_MOVE_TOhere.Quoted 4 lines
man7/fanotify.7 +0
-0...
Quoted 7 lines
+.B
FAN_ATTRIBman7/fanotify.7 +6
-0+A file or directory metadata was changed. +.TP +.B FAN_CREATE +A child file or directory was created in a watched parent. +.TP +.B FAN_DELETEman7/fanotify.7 See NOTES in · line 315
Quoted 10 lines
man7/fanotify.7 +10
-0+A child file or directory was deleted in a watched parent. +.TP +.B FAN_DELETE_SELF +A watched file or directory was deleted. +.TP +.B FAN_MOVED_FROM +A watched file or directory was moved from the current location. +.TP +.B FAN_MOVED_TO +A watched file or directory was moved to a new location.The same comment here about parent directory being actually marked.
man7/fanotify.7 This is a synonym for: · line 388
Quoted 6 lines
+.TP
+.I hdrman7/fanotify.7 +4
-0+This is a structure of type +.IR fanotify_event_info_header . +It is a generic header that contains information used to describe the type +of event."type of event" seems a bit unfortunate wording here since I'd expect that to be
FAN_CREATEor whatever. I'd rather choose something like "used to describe additional information attached to the event".
Quoted 13 lines
man7/fanotify.7 This is a synonym for: · line 396
Quoted 8 lines
man7/fanotify.7 +8
-0+For example, when an fanotify file descriptor is created using +.B FAN_REPORT_FID +the +.I info_type +field of this header is set to +.BR FAN_EVENT_INFO_TYPE_FID . +Event listeners can use this field to check that events of the correct +type are being received.I think here you should also speak about the 'len' field in the header which can be used to skip additional information that is not understood / uninteresting for the receiver of the event.
Well, one thing I think we should avoid is to overload reader with how those fields would be used in future expansion on the API.
There is a good example in this very man page:event_len
...
In the current implementation, the value of event_len is always FAN_EVENT_METADATA_LEN. However, the API is designed to allow variable-length structures to be returned in the future.
So I think 'len' field should get a similar treatment - In the current implementation, the value of len is always event_len - FAN_EVENT_METADATA_LEN. However, the API...
And now we see that the wording of event_len should be fixed with this patch, because the future is here ;-)
Thanks,
Amir.
Re: [RFC PATCH 1/1] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
In reply to Jan KaraThanks for the feedback Jan!
Quoted 17 lines · Jan Kara
Thanks for the manpage updates! Some small comments below.
man2/fanotify_mark.2 Create an event when a file or directory is opened. · line 201
Quoted 8 lines · Matthew Bobrowski
+.TP
+.BFAN_MOVED_FROMman2/fanotify_mark.2 +6
-0+Create an event when a marked file or directory is moved from the current +location. +.TP +.B FAN_MOVED_TO +Create an event when a marked file or directory is moved to a new +location.For these two events (like other directory events), marked thing is actually again the parent directory - i.e., these events trigger is something is moved to / from marked directory. So I think it would be clearer and use the same language like e.g. for
FAN_CREATEand speak about marked parent directory.
Sure, what changing this to:
--
.B FAN_MOVED_FROM
Create an event when a file or directory has been moved from a marked parent directory.
.TP
.B FAN_MOVED_TO
Create an event when a file or directory has been moved to a marked parent directory.
--
Do you think that's better? I think it's cleaner, but also at the same time more precise.
Quoted 7 lines
Quoted 7 lines
Without this flag, only events for files are created.
man2/fanotify_mark.2 +6
-0+The +.BR FAN_ONDIR +flag is reported in an event mask only if the +.I fanotify_fd +file descriptor has been initialized with the flag +.BR FAN_REPORT_FID .
Quoted 8 lines
man2/fanotify_mark.2 or · line 254
Quoted 5 lines
man2/fanotify_mark.2 +5
-0+In the context of directory entry events, such as +.BR FAN_CREATE , +.BR FAN_DELETE +and +.BR FAN_MOVEMaybe too early to speak about
FAN_MOVEhere as it's not defined yet? I'd rather explicitely useFAN_MOVE_FROMandFAN_MOVE_TOhere.
Yes, that makes more sense. Let's change it to what you've recommended.
Quoted 16 lines
Quoted 4 lines
man7/fanotify.7 +0
-0...
Quoted 11 lines
+.B
FAN_ATTRIBman7/fanotify.7 +10
-0+A file or directory metadata was changed. +.TP +.B FAN_CREATE +A child file or directory was created in a watched parent. +.TP +.B FAN_DELETE +A child file or directory was deleted in a watched parent. +.TP +.B FAN_DELETE_SELF +A watched file or directory was deleted.
Quoted 8 lines
man7/fanotify.7 See NOTES in · line 315
Quoted 6 lines
+.TP
+.BFAN_MOVED_FROMman7/fanotify.7 +4
-0+A watched file or directory was moved from the current location. +.TP +.B FAN_MOVED_TO +A watched file or directory was moved to a new location.The same comment here about parent directory being actually marked.
Sure, intending to change this to:
--
.B FAN_MOVED_FROM
A file or directory has been moved from a watched parent directory. .TP
.B FAN_MOVED_TO
A file or directory has been moved to a watched parent directory. --
Thoughts?
Quoted 10 lines
man7/fanotify.7 This is a synonym for: · line 388
Quoted 6 lines
+.TP
+.I hdrman7/fanotify.7 +4
-0+This is a structure of type +.IR fanotify_event_info_header . +It is a generic header that contains information used to describe the type +of event."type of event" seems a bit unfortunate wording here since I'd expect that to be
FAN_CREATEor whatever. I'd rather choose something like "used to describe additional information attached to the event".
Yes, that's much better wording.
Quoted 4 lines
Quoted 4 lines
man7/fanotify.7 +4
-0+For example, when an fanotify file descriptor is created using +.B FAN_REPORT_FID +the +.I info_type
Quoted 8 lines
man7/fanotify.7 This is a synonym for: · line 396
Quoted 4 lines
man7/fanotify.7 +4
-0+field of this header is set to +.BR FAN_EVENT_INFO_TYPE_FID . +Event listeners can use this field to check that events of the correct +type are being received.I think here you should also speak about the 'len' field in the header which can be used to skip additional information that is not understood / uninteresting for the receiver of the event.
I don't have any objections to add this as I do believe mentioning it has added benefit. Perhaps we could consider adding in a section which describes all the fanotify_event_info_header fields? Maybe it's not necessary though, and just mentioning these two fields here would be enough. Thoughts?
Quoted 11 lines
Quoted 11 lines
+.TP
+.I fsidman7/fanotify.7 +9
-0+This is a unique identifier of the filesystem containing the object +associated with the event. +It is a structure of type +.I __kernel_fsid_t +and contains the same value as +.I f_fsid +when calling +.BR statfs (2). +.TP
Quoted 8 lines
man7/fanotify.7 This is a synonym for: · line 413
Quoted 6 lines
+.I
file_handleman7/fanotify.7 +5
-0+This is a variable length structure of type +.IR file_handle . +It is an opaque handle that corresponds to a specified object on a +filesystem as returned by +.BR name_at_handle_at (2) .
name_to_handle_at(2)
Woops.
Quoted 5 lines
Quoted 5 lines
+.PP
man7/fanotify.7 +4
-0+The second example program output was captured from fanotify_fid. +There are two discrete invocations to this program with each invocation +accommodating a different action performed on a watched object. +This first session shows a mark being placed on
Quoted 8 lines
man7/fanotify.7 After the file was closed, a · line 716
Quoted 7 lines
+.IR
/home/user.man7/fanotify.7 +6
-0+This is followed by a subsequent regular file +.IR /home/user/testfile.txt +being created. +This results in a +.B FAN_CREATE +event being created and reported against the files parent watched^^^ file's ?
Woops * 2.
Signature · 1 line
Matthew Bobrowski
Jan Kara
reviewerRe: [RFC PATCH 1/1] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
Quoted 31 lines · Matthew Bobrowski
Quoted 17 lines · Jan Kara
Thanks for the manpage updates! Some small comments below.
man2/fanotify_mark.2 Create an event when a file or directory is opened. · line 201
Quoted 8 lines · Matthew Bobrowski
+.TP
+.BFAN_MOVED_FROMman2/fanotify_mark.2 +6
-0+Create an event when a marked file or directory is moved from the current +location. +.TP +.B FAN_MOVED_TO +Create an event when a marked file or directory is moved to a new +location.For these two events (like other directory events), marked thing is actually again the parent directory - i.e., these events trigger is something is moved to / from marked directory. So I think it would be clearer and use the same language like e.g. for
FAN_CREATEand speak about marked parent directory.Sure, what changing this to:
--
.BFAN_MOVED_FROM
Create an event when a file or directory has been moved from a marked parent directory.
.TP
.BFAN_MOVED_TO
Create an event when a file or directory has been moved to a marked parent directory.
--
Quoted 2 lines
Do you think that's better? I think it's cleaner, but also at the same time more precise.
Yes, I think that's better.
Quoted 30 lines
Quoted 11 lines
Quoted 11 lines
+.B
FAN_ATTRIBman7/fanotify.7 +10
-0+A file or directory metadata was changed. +.TP +.B FAN_CREATE +A child file or directory was created in a watched parent. +.TP +.B FAN_DELETE +A child file or directory was deleted in a watched parent. +.TP +.B FAN_DELETE_SELF +A watched file or directory was deleted.Quoted 8 lines
man7/fanotify.7 See NOTES in · line 315
Quoted 6 lines
+.TP
+.BFAN_MOVED_FROMman7/fanotify.7 +4
-0+A watched file or directory was moved from the current location. +.TP +.B FAN_MOVED_TO +A watched file or directory was moved to a new location.The same comment here about parent directory being actually marked.
Sure, intending to change this to:
--
.BFAN_MOVED_FROM
A file or directory has been moved from a watched parent directory. .TP
.BFAN_MOVED_TO
A file or directory has been moved to a watched parent directory. --
Quoted 1 line
Thoughts?
Looks good to me!
Quoted 13 lines
Quoted 4 lines
Quoted 4 lines
man7/fanotify.7 +4
-0+For example, when an fanotify file descriptor is created using +.B FAN_REPORT_FID +the +.I info_typeQuoted 8 lines
man7/fanotify.7 This is a synonym for: · line 396
Quoted 4 lines
man7/fanotify.7 +4
-0+field of this header is set to +.BR FAN_EVENT_INFO_TYPE_FID . +Event listeners can use this field to check that events of the correct +type are being received.I think here you should also speak about the 'len' field in the header which can be used to skip additional information that is not understood / uninteresting for the receiver of the event.
Quoted 4 lines
I don't have any objections to add this as I do believe mentioning it has added benefit. Perhaps we could consider adding in a section which describes all the
fanotify_event_info_headerfields? Maybe it's not necessary though, and just mentioning these two fields here would be enough. Thoughts?
Well, there are just two fields - 'info_type' and 'len'. There's also 'pad' but that doesn't really count ;). So I think that briefly explaining 'len' is all that's needed. If you want to formalize this a bit more in a separate section, I'm not opposed but I don't think it's really necessary.
Thanks!
Honza
Signature · 2 lines
Jan Kara <[email protected]> SUSE Labs, CR
Re: [RFC PATCH 1/1] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
Quoted 18 lines
Quoted 13 lines
Quoted 4 lines
Quoted 4 lines
man7/fanotify.7 +4
-0+For example, when an fanotify file descriptor is created using +.B FAN_REPORT_FID +the +.I info_typeQuoted 8 lines
man7/fanotify.7 This is a synonym for: · line 396
Quoted 4 lines
man7/fanotify.7 +4
-0+field of this header is set to +.BR FAN_EVENT_INFO_TYPE_FID . +Event listeners can use this field to check that events of the correct +type are being received.I think here you should also speak about the 'len' field in the header which can be used to skip additional information that is not understood / uninteresting for the receiver of the event.
Quoted 4 lines
I don't have any objections to add this as I do believe mentioning it has added benefit. Perhaps we could consider adding in a section which describes all the
fanotify_event_info_headerfields? Maybe it's not necessary though, and just mentioning these two fields here would be enough. Thoughts?
Quoted 5 lines
Well, there are just two fields - '
info_type' and 'len'. There's also 'pad' but that doesn't really count ;). So I think that briefly explaining 'len' is all that's needed. If you want to formalize this a bit more in a separate section, I'm not opposed but I don't think it's really necessary.
I did not get a reply from Matthew, so to make sure my comment about 'len' wasn't missed.
I think 'len' field should get a similar treatment to 'event_len' - "In the current implementation, the value of len is always (event_len - FAN_EVENT_METADATA_LEN). However, the API is designed..."
And the same sentence about 'event_len' field is now no longer correct so it should be updated, e.g.:
event_len
...
Without FAN_REPORT_FID, the value of event_len is always FAN_EVENT_METADATA_LEN. With FAN_REPORT_FID, event_len also includes the variable length file identifier.
Thanks,
Amir.
Re: [RFC PATCH 1/1] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events
Quoted 18 lines · Amir Goldstein
Quoted 18 lines
Quoted 17 lines
Quoted 4 lines
Quoted 4 lines
man7/fanotify.7 +4
-0+For example, when an fanotify file descriptor is created using +.B FAN_REPORT_FID +the +.I info_typeQuoted 8 lines
man7/fanotify.7 This is a synonym for: · line 396
Quoted 4 lines
man7/fanotify.7 +4
-0+field of this header is set to +.BR FAN_EVENT_INFO_TYPE_FID . +Event listeners can use this field to check that events of the correct +type are being received.I think here you should also speak about the 'len' field in the header which can be used to skip additional information that is not understood / uninteresting for the receiver of the event.
I don't have any objections to add this as I do believe mentioning it has added benefit. Perhaps we could consider adding in a section which describes all the
fanotify_event_info_headerfields? Maybe it's not necessary though, and just mentioning these two fields here would be enough. Thoughts?
Quoted 4 lines
Quoted 4 lines
Well, there are just two fields - '
info_type' and 'len'. There's also 'pad' but that doesn't really count ;). So I think that briefly explaining 'len' is all that's needed. If you want to formalize this a bit more in a separate section, I'm not opposed but I don't think it's really necessary.
Jan, sure I'd have to agree with you, but was just thinking to put the thought out there.
Quoted 2 lines
I did not get a reply from Matthew, so to make sure my comment about 'len' wasn't missed.
Sorry Amir, I definitely did see the note you dropped about the 'len' field. Apologies for not getting back to you directly about that.
Quoted 5 lines
I think 'len' field should get a similar treatment to '
event_len' - "In the current implementation, the value of len is always (event_len-FAN_EVENT_METADATA_LEN). However, the API is designed..."
Quoted 8 lines
And the same sentence about '
event_len' field is now no longer correct so it should be updated, e.g.:
event_len
...
WithoutFAN_REPORT_FID, the value ofevent_lenis alwaysFAN_EVENT_METADATA_LEN. WithFAN_REPORT_FID,event_lenalso includes the variable length file identifier.
Understood, I will make sure to incorporate these details into my revised patch.
Signature · 1 line
Matthew Bobrowski