fanotify: Document FAN_PRE_ACCESS event
PATCH 1/1 fanotify: Document FAN_PRE_ACCESS event
The new FAN_PRE_ACCESS events are created before access to a file range, to provides an opportunity for the event listener to modify the content of the object before the user can accesss it.
Those events are available for group in class FAN_CLASS_PRE_CONTENT They are reported with FAN_EVENT_INFO_TYPE_RANGE info record.
--- man/man2/fanotify_init.2 | 4 ++-- man/man2/fanotify_mark.2 | 14 +++++++++++++ man/man7/fanotify.7 | 43 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 57 insertions(+), 4 deletions(-)
man/man2/fanotify_init.2 +2 -2
@@ -57,8 +57,8 @@ Only one of the following notification classes may be specified in .B FAN_CLASS_PRE_CONTENT This value allows the receipt of events notifying that a file has been accessed and events for permission decisions if a file may be accessed. -It is intended for event listeners that need to access files before they -contain their final data. +It is intended for event listeners that may need to write data to files +before their final data can be accessed. This notification class might be used by hierarchical storage managers, for example. Use of this flag requires the
man/man2/fanotify_mark.2 +14 -0
@@ -445,6 +445,20 @@ or .B FAN_CLASS_CONTENT is required. .TP +.BR FAN_PRE_ACCESS " (since Linux 6.14)" +.\" commit 4f8afa33817a6420398d1c177c6e220a05081f51 +Create an event before read or write access to a file range, +that provides an opportunity for the event listener +to modify the content of the file +before access to the content +in the specified range. +An additional information record of type +.B FAN_EVENT_INFO_TYPE_RANGE +is returned for each event in the read buffer. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +is required. +.TP .B FAN_ONDIR Create events for directories\[em]for example, when .BR opendir (3),
man/man7/fanotify.7 +41 -2
61 lines not on this page · raw message
Signature · 1 line
2.34.1
Quoted 8 lines · Amir Goldstein
The new
FAN_PRE_ACCESSevents are created before access to a file range, to provides an opportunity for the event listener to modify the content of the object before the user can accesss it.Those events are available for group in class
FAN_CLASS_PRE_CONTENTThey are reported withFAN_EVENT_INFO_TYPE_RANGEinfo record.Signed-off-by Amir Goldstein <[email protected]>
Looks good. Feel free to add:
Honza
Quoted 117 lines
--- man/man2/fanotify_init.2 | 4 ++-- man/man2/fanotify_mark.2 | 14 +++++++++++++ man/man7/fanotify.7 | 43 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 57 insertions(+), 4 deletions(-)man/man2/fanotify_init.2 +2
-2@@ -57,8 +57,8 @@ Only one of the following notification classes may be specified in .B FAN_CLASS_PRE_CONTENT This value allows the receipt of events notifying that a file has been accessed and events for permission decisions if a file may be accessed. -It is intended for event listeners that need to access files before they -contain their final data. +It is intended for event listeners that may need to write data to files +before their final data can be accessed. This notification class might be used by hierarchical storage managers, for example. Use of this flag requires theman/man2/fanotify_mark.2 +14
-0@@ -445,6 +445,20 @@ or .B FAN_CLASS_CONTENT is required. .TP +.BR FAN_PRE_ACCESS " (since Linux 6.14)" +.\" commit 4f8afa33817a6420398d1c177c6e220a05081f51 +Create an event before read or write access to a file range, +that provides an opportunity for the event listener +to modify the content of the file +before access to the content +in the specified range. +An additional information record of type +.B FAN_EVENT_INFO_TYPE_RANGE +is returned for each event in the read buffer. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +is required. +.TP .B FAN_ONDIR Create events for directories\[em]for example, when .BR opendir (3),man/man7/fanotify.7 +41
-2@@ -247,6 +247,26 @@ struct fanotify_event_info_error { .EE .in .P +In case of +.B FAN_PRE_ACCESS +events, +an additional information record describing the access range +is returned alongside the generic +.I fanotify_event_metadata +structure within the read buffer. +This structure is defined as follows: +.P +.in +4n +.EX +struct fanotify_event_info_range { + struct fanotify_event_info_header hdr; + __u32 pad; + __u64 offset; + __u64 count; +}; +.EE +.in +.P All information records contain a nested structure of type .IR fanotify_event_info_header . This structure holds meta-information about the information record@@ -509,8 +529,9 @@ The value of this field can be set to one of the following: .BR FAN_EVENT_INFO_TYPE_FID , .BR FAN_EVENT_INFO_TYPE_DFID , .BR FAN_EVENT_INFO_TYPE_DFID_NAME , -or -.BR FAN_EVENT_INFO_TYPE_PIDFD . +.BR FAN_EVENT_INFO_TYPE_PIDFD , +.BR FAN_EVENT_INFO_TYPE_ERROR , +.BR FAN_EVENT_INFO_TYPE_RANGE . The value set for this field is dependent on the flags that have been supplied to .BR fanotify_init (2).@@ -711,6 +732,24 @@ Identifies the type of error that occurred. This is a counter of the number of errors suppressed since the last error was read. .P +The fields of the +.I fanotify_event_info_range +structure are as follows: +.TP +.I hdr +This is a structure of type +.IR fanotify_event_info_header . +The +.I info_type +field is set to +.BR FAN_EVENT_INFO_TYPE_RANGE . +.TP +.I count +The number of bytes being read or written to the file. +.TP +.I offset +The offset from which bytes are read or written to the file. +.P The following macros are provided to iterate over a buffer containing fanotify event metadata returned by a .BR read (2)Signature · 1 line
2.34.1
Signature · 2 lines
Jan Kara <[email protected]> SUSE Labs, CR
Alejandro Colomar
maintainerHi Amir,
Quoted 98 lines · Amir Goldstein
The new
FAN_PRE_ACCESSevents are created before access to a file range, to provides an opportunity for the event listener to modify the content of the object before the user can accesss it.Those events are available for group in class
FAN_CLASS_PRE_CONTENTThey are reported withFAN_EVENT_INFO_TYPE_RANGEinfo record.Signed-off-by Amir Goldstein <[email protected]>--- man/man2/fanotify_init.2 | 4 ++-- man/man2/fanotify_mark.2 | 14 +++++++++++++ man/man7/fanotify.7 | 43 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 57 insertions(+), 4 deletions(-)man/man2/fanotify_init.2 +2
-2@@ -57,8 +57,8 @@ Only one of the following notification classes may be specified in .B FAN_CLASS_PRE_CONTENT This value allows the receipt of events notifying that a file has been accessed and events for permission decisions if a file may be accessed. -It is intended for event listeners that need to access files before they -contain their final data. +It is intended for event listeners that may need to write data to files +before their final data can be accessed. This notification class might be used by hierarchical storage managers, for example. Use of this flag requires theman/man2/fanotify_mark.2 +14
-0@@ -445,6 +445,20 @@ or .B FAN_CLASS_CONTENT is required. .TP +.BR FAN_PRE_ACCESS " (since Linux 6.14)" +.\" commit 4f8afa33817a6420398d1c177c6e220a05081f51 +Create an event before read or write access to a file range, +that provides an opportunity for the event listener +to modify the content of the file +before access to the content +in the specified range. +An additional information record of type +.B FAN_EVENT_INFO_TYPE_RANGE +is returned for each event in the read buffer. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +is required. +.TP .B FAN_ONDIR Create events for directories\[em]for example, when .BR opendir (3),man/man7/fanotify.7 +23
-2@@ -247,6 +247,26 @@ struct fanotify_event_info_error { .EE .in .P +In case of +.B FAN_PRE_ACCESS +events, +an additional information record describing the access range +is returned alongside the generic +.I fanotify_event_metadata +structure within the read buffer. +This structure is defined as follows: +.P +.in +4n +.EX +struct fanotify_event_info_range { + struct fanotify_event_info_header hdr; + __u32 pad; + __u64 offset; + __u64 count; +}; +.EE +.in +.P All information records contain a nested structure of type .IR fanotify_event_info_header . This structure holds meta-information about the information record@@ -509,8 +529,9 @@ The value of this field can be set to one of the following: .BR FAN_EVENT_INFO_TYPE_FID , .BR FAN_EVENT_INFO_TYPE_DFID , .BR FAN_EVENT_INFO_TYPE_DFID_NAME , -or -.BR FAN_EVENT_INFO_TYPE_PIDFD . +.BR FAN_EVENT_INFO_TYPE_PIDFD , +.BR FAN_EVENT_INFO_TYPE_ERROR , +.BR FAN_EVENT_INFO_TYPE_RANGE . The value set for this field is dependent on the flags that have been supplied to .BR fanotify_init (2).
man/man7/fanotify.7 Identifies the type of error that occurred. · line 739
Quoted 8 lines
man/man7/fanotify.7 +5
-0@@ -711,6 +732,24 @@ Identifies the type of error that occurred. This is a counter of the number of errors suppressed since the last error was read. .P +The fields of the +.I fanotify_event_info_range +structure are as follows: +.TP +.I hdr
We should use .hdr here too (and in the fields below, '.' too), right?
Cheers,
Alex
Quoted 19 lines
man/man7/fanotify.7 +13
-0+This is a structure of type +.IR fanotify_event_info_header . +The +.I info_type +field is set to +.BR FAN_EVENT_INFO_TYPE_RANGE . +.TP +.I count +The number of bytes being read or written to the file. +.TP +.I offset +The offset from which bytes are read or written to the file. +.P The following macros are provided to iterate over a buffer containing fanotify event metadata returned by a .BR read (2)Signature · 1 line
2.34.1
Signature · 3 lines
<https://www.alejandro-colomar.es/> <https://www.alejandro-colomar.es:8443/> <http://www.alejandro-colomar.es:8080/>
Quoted 104 lines · Alejandro Colomar
Hi Amir,
Quoted 100 lines · Amir Goldstein
The new
FAN_PRE_ACCESSevents are created before access to a file range, to provides an opportunity for the event listener to modify the content of the object before the user can accesss it.Those events are available for group in class
FAN_CLASS_PRE_CONTENTThey are reported withFAN_EVENT_INFO_TYPE_RANGEinfo record.Signed-off-by Amir Goldstein <[email protected]>--- man/man2/fanotify_init.2 | 4 ++-- man/man2/fanotify_mark.2 | 14 +++++++++++++ man/man7/fanotify.7 | 43 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 57 insertions(+), 4 deletions(-)man/man2/fanotify_init.2 +2
-2@@ -57,8 +57,8 @@ Only one of the following notification classes may be specified in .B FAN_CLASS_PRE_CONTENT This value allows the receipt of events notifying that a file has been accessed and events for permission decisions if a file may be accessed. -It is intended for event listeners that need to access files before they -contain their final data. +It is intended for event listeners that may need to write data to files +before their final data can be accessed. This notification class might be used by hierarchical storage managers, for example. Use of this flag requires theman/man2/fanotify_mark.2 +14
-0@@ -445,6 +445,20 @@ or .B FAN_CLASS_CONTENT is required. .TP +.BR FAN_PRE_ACCESS " (since Linux 6.14)" +.\" commit 4f8afa33817a6420398d1c177c6e220a05081f51 +Create an event before read or write access to a file range, +that provides an opportunity for the event listener +to modify the content of the file +before access to the content +in the specified range. +An additional information record of type +.B FAN_EVENT_INFO_TYPE_RANGE +is returned for each event in the read buffer. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +is required. +.TP .B FAN_ONDIR Create events for directories\[em]for example, when .BR opendir (3),man/man7/fanotify.7 +23
-2@@ -247,6 +247,26 @@ struct fanotify_event_info_error { .EE .in .P +In case of +.B FAN_PRE_ACCESS +events, +an additional information record describing the access range +is returned alongside the generic +.I fanotify_event_metadata +structure within the read buffer. +This structure is defined as follows: +.P +.in +4n +.EX +struct fanotify_event_info_range { + struct fanotify_event_info_header hdr; + __u32 pad; + __u64 offset; + __u64 count; +}; +.EE +.in +.P All information records contain a nested structure of type .IR fanotify_event_info_header . This structure holds meta-information about the information record@@ -509,8 +529,9 @@ The value of this field can be set to one of the following: .BR FAN_EVENT_INFO_TYPE_FID , .BR FAN_EVENT_INFO_TYPE_DFID , .BR FAN_EVENT_INFO_TYPE_DFID_NAME , -or -.BR FAN_EVENT_INFO_TYPE_PIDFD . +.BR FAN_EVENT_INFO_TYPE_PIDFD , +.BR FAN_EVENT_INFO_TYPE_ERROR , +.BR FAN_EVENT_INFO_TYPE_RANGE . The value set for this field is dependent on the flags that have been supplied to .BR fanotify_init (2).@@ -711,6 +732,24 @@ Identifies the type of error that occurred. This is a counter of the number of errors suppressed since the last error was read.
Quoted 9 lines
man/man7/fanotify.7 Identifies the type of error that occurred. · line 739
Quoted 6 lines
man/man7/fanotify.7 +5
-0.P +The fields of the +.I fanotify_event_info_range +structure are as follows: +.TP +.I hdrWe should use .hdr here too (and in the fields below, '.' too), right?
Sure that was your idea.
I am fine with it.
I guess it could be changed later with other instances,
Thanks,
Amir.
Alejandro Colomar
maintainerQuoted 115 lines · Amir Goldstein
Quoted 104 lines · Alejandro Colomar
Hi Amir,
Quoted 100 lines · Amir Goldstein
The new
FAN_PRE_ACCESSevents are created before access to a file range, to provides an opportunity for the event listener to modify the content of the object before the user can accesss it.Those events are available for group in class
FAN_CLASS_PRE_CONTENTThey are reported withFAN_EVENT_INFO_TYPE_RANGEinfo record.Signed-off-by Amir Goldstein <[email protected]>--- man/man2/fanotify_init.2 | 4 ++-- man/man2/fanotify_mark.2 | 14 +++++++++++++ man/man7/fanotify.7 | 43 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 57 insertions(+), 4 deletions(-)man/man2/fanotify_init.2 +2
-2@@ -57,8 +57,8 @@ Only one of the following notification classes may be specified in .B FAN_CLASS_PRE_CONTENT This value allows the receipt of events notifying that a file has been accessed and events for permission decisions if a file may be accessed. -It is intended for event listeners that need to access files before they -contain their final data. +It is intended for event listeners that may need to write data to files +before their final data can be accessed. This notification class might be used by hierarchical storage managers, for example. Use of this flag requires theman/man2/fanotify_mark.2 +14
-0@@ -445,6 +445,20 @@ or .B FAN_CLASS_CONTENT is required. .TP +.BR FAN_PRE_ACCESS " (since Linux 6.14)" +.\" commit 4f8afa33817a6420398d1c177c6e220a05081f51 +Create an event before read or write access to a file range, +that provides an opportunity for the event listener +to modify the content of the file +before access to the content +in the specified range. +An additional information record of type +.B FAN_EVENT_INFO_TYPE_RANGE +is returned for each event in the read buffer. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +is required. +.TP .B FAN_ONDIR Create events for directories\[em]for example, when .BR opendir (3),man/man7/fanotify.7 +23
-2@@ -247,6 +247,26 @@ struct fanotify_event_info_error { .EE .in .P +In case of +.B FAN_PRE_ACCESS +events, +an additional information record describing the access range +is returned alongside the generic +.I fanotify_event_metadata +structure within the read buffer. +This structure is defined as follows: +.P +.in +4n +.EX +struct fanotify_event_info_range { + struct fanotify_event_info_header hdr; + __u32 pad; + __u64 offset; + __u64 count; +}; +.EE +.in +.P All information records contain a nested structure of type .IR fanotify_event_info_header . This structure holds meta-information about the information record@@ -509,8 +529,9 @@ The value of this field can be set to one of the following: .BR FAN_EVENT_INFO_TYPE_FID , .BR FAN_EVENT_INFO_TYPE_DFID , .BR FAN_EVENT_INFO_TYPE_DFID_NAME , -or -.BR FAN_EVENT_INFO_TYPE_PIDFD . +.BR FAN_EVENT_INFO_TYPE_PIDFD , +.BR FAN_EVENT_INFO_TYPE_ERROR , +.BR FAN_EVENT_INFO_TYPE_RANGE . The value set for this field is dependent on the flags that have been supplied to .BR fanotify_init (2).@@ -711,6 +732,24 @@ Identifies the type of error that occurred. This is a counter of the number of errors suppressed since the last error was read.Quoted 9 lines
man/man7/fanotify.7 Identifies the type of error that occurred. · line 739
Quoted 6 lines
man/man7/fanotify.7 +5
-0.P +The fields of the +.I fanotify_event_info_range +structure are as follows: +.TP +.I hdrWe should use .hdr here too (and in the fields below, '.' too), right?
Quoted 4 lines
Sure that was your idea.
I am fine with it.I guess it could be changed later with other instances,
Okay, I'll do it post-merge.
Cheers,
Alex
Quoted 3 lines
Thanks,
Amir.
Signature · 3 lines
<https://www.alejandro-colomar.es/> <https://www.alejandro-colomar.es:8443/> <http://www.alejandro-colomar.es:8080/>