Re: [PATCH v2] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Amir,

On 2023-09-06 09:42, Amir Goldstein wrote:
> A flag to indicate that the requested file_handle is not intended
> to be used for open_by_handle_at(2) and may be needed to identify
> filesystem objects reported in fanotify events.
> 
> Reviewed-by: Jan Kara <jack@xxxxxxx>
> Acked-by: Christian Brauner <brauner@xxxxxxxxxx>
> Signed-off-by: Amir Goldstein <amir73il@xxxxxxxxx>

Patch applied.  Thank you and the reviewers!

Cheers,
Alex

> ---
> 
> Hi Alejandro,
> 
> This is a followup on AT_HANDLE_FID feature from v6.5.
> 
> Thanks,
> Amir.
> 
> Changes from v1:
> - Added RVB/ACK
> - Spelling fixes
> 
>  man2/fanotify_mark.2     | 11 +++++++++--
>  man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
>  2 files changed, 48 insertions(+), 5 deletions(-)
> 
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 3f85deb23..8e885af69 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -743,10 +743,17 @@ do not specify a directory.
>  .B EOPNOTSUPP
>  The object indicated by
>  .I pathname
> -is associated with a filesystem that does not support the encoding of file
> -handles.
> +is associated with a filesystem
> +that does not support the encoding of file handles.
>  This error can be returned only with an fanotify group that identifies
>  filesystem objects by file handles.
> +Calling
> +.BR name_to_handle_at (2)
> +with the flag
> +.BR AT_HANDLE_FID " (since Linux 6.5)"
> +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> +can be used as a test
> +to check if a filesystem supports reporting events with file handles.
>  .TP
>  .B EPERM
>  The operation is not permitted because the caller lacks a required capability.
> diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2
> index 4061faea9..3e38eb8e3 100644
> --- a/man2/open_by_handle_at.2
> +++ b/man2/open_by_handle_at.2
> @@ -109,17 +109,44 @@ structure as an opaque data type: the
>  .I handle_type
>  and
>  .I f_handle
> -fields are needed only by a subsequent call to
> +fields can be used in a subsequent call to
>  .BR open_by_handle_at ().
> +The caller can also use the opaque
> +.I file_handle
> +to compare the identity of filesystem objects
> +that were queried at different times and possibly
> +at different paths.
> +The
> +.BR fanotify (7)
> +subsystem can report events
> +with an information record containing a
> +.I file_handle
> +to identify the filesystem object.
>  .PP
>  The
>  .I flags
>  argument is a bit mask constructed by ORing together zero or more of
> -.B AT_EMPTY_PATH
> +.BR AT_HANDLE_FID ,
> +.BR AT_EMPTY_PATH ,
>  and
>  .BR AT_SYMLINK_FOLLOW ,
>  described below.
>  .PP
> +When
> +.I flags
> +contain the
> +.BR AT_HANDLE_FID " (since Linux 6.5)"
> +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
> +flag, the caller indicates that the returned
> +.I file_handle
> +is needed to identify the filesystem object,
> +and not for opening the file later,
> +so it should be expected that a subsequent call to
> +.BR open_by_handle_at ()
> +with the returned
> +.I file_handle
> +may fail.
> +.PP
>  Together, the
>  .I pathname
>  and
> @@ -363,8 +390,14 @@ capability.
>  .B ESTALE
>  The specified
>  .I handle
> -is not valid.
> +is not valid for opening a file.
>  This error will occur if, for example, the file has been deleted.
> +This error can also occur if the
> +.I handle
> +was acquired using the
> +.B AT_HANDLE_FID
> +flag and the filesystem does not support
> +.BR open_by_handle_at ().
>  .SH VERSIONS
>  FreeBSD has a broadly similar pair of system calls in the form of
>  .BR getfh ()
> @@ -386,6 +419,9 @@ file handles, for example,
>  .IR /proc ,
>  .IR /sys ,
>  and various network filesystems.
> +Some filesystems support the translation of pathnames to
> +file handles, but do not support using those file handles in
> +.BR open_by_handle_at ().
>  .PP
>  A file handle may become invalid ("stale") if a file is deleted,
>  or for other filesystem-specific reasons.

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

Attachment: OpenPGP_signature.asc
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux