Hi Amir,
On Sun, Mar 30, 2025 at 05:33:26PM +0200, Amir Goldstein wrote:
> Document FAN_DENY_ERRNO(), that was added in v6.13 and the
> FAN_RESPONSE_INFO_AUDIT_RULE extended response info record
> that was added in v6.3.
>
> Cc: Richard Guy Briggs <rgb@xxxxxxxxxx>
> Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>
> ---
>
> Alejandro,
>
> I was working on man page updates to fanotify features that landed
> in v6.14 and found a few bits from v6.3 that were out of date, so
> I added them along with this change.
>
> If you want me to split them out I can, but I did not see much point.
I prefer them in two patches. You can send them in the same patch set,
though.
> This change to the documentation of fanotify permission event response
> is independent of the previous patches I posted to document the new
> FAN_PRE_ACCESS event (also v6.14) and the fanotify_init(2) flag
> FAN_REPORT_FD_ERROR (v6.13).
>
> There is another fanotify feature in v6.14 (mount events).
> I will try to catch up on documenting that one as well.
>
> Thanks,
> Amir.
>
> man/man7/fanotify.7 | 60 ++++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 59 insertions(+), 1 deletion(-)
>
> diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
> index 6f3a9496e..c7b53901a 100644
> --- a/man/man7/fanotify.7
> +++ b/man/man7/fanotify.7
> @@ -820,7 +820,7 @@ This is the file descriptor from the structure
> .TP
> .I response
> This field indicates whether or not the permission is to be granted.
> -Its value must be either
> +Its value must contain either the flag
This seems unrelated. Please keep it out of the patches. If you want
to do it, please have a third trivial patch with "wfix" in the subject.
> .B FAN_ALLOW
> to allow the file operation or
> .B FAN_DENY
> @@ -829,6 +829,24 @@ to deny the file operation.
> If access is denied, the requesting application call will receive an
> .B EPERM
> error.
> +Since Linux 6.14,
> +.\" commit b4b2ff4f61ded819bfa22e50fdec7693f51cbbee
> +if a notification group is initialized with class
> +.BR FAN_CLASS_PRE_CONTENT ,
> +the following error values could be returned to the application
> +by setting the
> +.I response
> +value using the
> +.BR FAN_DENY_ERRNO(err)
This formatting is incorrect. BR means alternating Bold and Roman, but
this only has one token.
> +macro:
> +.BR EPERM ,
> +.BR EIO ,
> +.BR EBUSY ,
> +.BR ETXTBSY ,
> +.BR EAGAIN ,
> +.BR ENOSPC ,
> +.BR EDQUOT .
Should we have a manual page for FAN_DENY_ERRNO()? (I think we should.)
I don't understand how it's supposed to work from this paragraph.
> +.P
> Additionally, if the notification group has been created with the
> .B FAN_ENABLE_AUDIT
> flag, then the
> @@ -838,6 +856,46 @@ flag can be set in the
> field.
> In that case, the audit subsystem will log information about the access
> decision to the audit logs.
Do we want to start a new paragraph maybe?
> +Since Linux 6.3,
> +.\" commit 70529a199574c15a40f46b14256633b02ba10ca2
> +the
> +.B FAN_INFO
> +flag can be set in the
> +.I response
> +to indicate that extra variable length response record follows struct
s/variable length/variable-length/
And we usually say 'XXX structure' instead of 'struct XXX'.
> +.IR fanotify_response .
The above sentence is too long. I'd split it into two:
Since Linux 6.3, the FAN_INFO flag can be set in the response field. It
indicates that an extra variable-length response record follows the
fanotify_response structure.
> +Extra response records start with a common header:
> +.P
> +.in +4n
> +.EX
> +struct fanotify_response_info_header {
> + __u8 type;
> + __u8 pad;
> + __u16 len;
> +};
> +.EE
> +.in
> +.P
> +The value of
> +.I type
I'd say '.type' instead of 'type'. I know there's no consistency about
it, but I'm going to globally fix that eventually. Let's do it good for
new documentation. The '.' allows one to easily know that we're talking
about a struct or union member.
Have a lovely day!
Alex
> +determines the format of the extra response record.
> +In case the value of
> +.I type
> +is
> +.BR FAN_RESPONSE_INFO_AUDIT_RULE ,
> +the following response record is expected
> +with extra details for the audit log:
> +.P
> +.in +4n
> +.EX
> +struct fanotify_response_info_audit_rule {
> + struct fanotify_response_info_header hdr;
> + __u32 rule_number;
> + __u32 subj_trust;
> + __u32 obj_trust;
> +};
> +.EE
> +.in
> .\"
> .SS Monitoring filesystems for errors
> A single
> --
> 2.34.1
>
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
