* [PATCH v2] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag
@ 2023-09-06 7:42 Amir Goldstein
2023-09-13 14:58 ` Alejandro Colomar
0 siblings, 1 reply; 2+ messages in thread
From: Amir Goldstein @ 2023-09-06 7:42 UTC (permalink / raw)
To: Alejandro Colomar
Cc: Tom Schwindl, Jan Kara, Jeff Layton, Christian Brauner, linux-man
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@suse.cz>
Acked-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
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.
--
2.34.1
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH v2] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag
2023-09-06 7:42 [PATCH v2] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag Amir Goldstein
@ 2023-09-13 14:58 ` Alejandro Colomar
0 siblings, 0 replies; 2+ messages in thread
From: Alejandro Colomar @ 2023-09-13 14:58 UTC (permalink / raw)
To: Amir Goldstein
Cc: Tom Schwindl, Jan Kara, Jeff Layton, Christian Brauner, linux-man
[-- Attachment #1.1: Type: text/plain, Size: 4219 bytes --]
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@suse.cz>
> Acked-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2023-09-13 14:58 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-09-06 7:42 [PATCH v2] name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag Amir Goldstein
2023-09-13 14:58 ` Alejandro Colomar
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.