Skip to contentSkip to conversation

name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

PATCH Superseded Amir Goldstein 4 participants 5 messages Sep 3, 2023 – Sep 6, 2023

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag

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.

---

Hi Alejandro,

This is a followup on AT_HANDLE_FID feature from v6.5.

Thanks,
Amir.

 man2/fanotify_mark.2     | 11 +++++++++--
 man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 5 deletions(-)
man2/fanotify_mark.2 +9 -2
index 3f85deb23..8e885af69 100644
@@ -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.
man2/open_by_handle_at.2 +39 -3

70 lines not on this page · raw message

Signature · 1 line
2.34.1
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 5 lines · Amir Goldstein

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.

Looks good to me. Feel free to add:

Honza

Quoted 117 lines

---

Hi Alejandro,

This is a followup on AT_HANDLE_FID feature from v6.5.

Thanks,
Amir.

 man2/fanotify_mark.2     | 11 +++++++++--
 man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 5 deletions(-)
man2/fanotify_mark.2 +9 -2
index 3f85deb23..8e885af69 100644
@@ -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.
man2/open_by_handle_at.2 +39 -3
index 4061faea9..4cfa21d9c 100644
@@ -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 aquired 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 filesystem 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.
Signature · 1 line
2.34.1
Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#3 lore raw
In reply to Amir Goldstein

Hi,

Quoted 94 lines · Amir Goldstein

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.

---

Hi Alejandro,

This is a followup on AT_HANDLE_FID feature from v6.5.

Thanks,
Amir.

 man2/fanotify_mark.2     | 11 +++++++++--
 man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 5 deletions(-)
man2/fanotify_mark.2 +9 -2
index 3f85deb23..8e885af69 100644
@@ -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.
man2/open_by_handle_at.2 +29 -2
index 4061faea9..4cfa21d9c 100644
@@ -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

man2/open_by_handle_at.2 capability. · line 397

Quoted 9 lines
man2/open_by_handle_at.2 +4 -1
@@ -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 aquired using the

This should probably be s/aquired/acquired/

man2/open_by_handle_at.2 file handles, for example, · line 422

Quoted 11 lines
man2/open_by_handle_at.2 +4 -0
+.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 filesystem support the translation of pathnames to

You should use the plural, filesystems, here.

Quoted 5 lines
man2/open_by_handle_at.2 +2 -0
+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.
#4 lore raw
Quoted 110 lines · Tom Schwindl

Hi,

Quoted 94 lines · Amir Goldstein

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.

---

Hi Alejandro,

This is a followup on AT_HANDLE_FID feature from v6.5.

Thanks,
Amir.

 man2/fanotify_mark.2     | 11 +++++++++--
 man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 5 deletions(-)
man2/fanotify_mark.2 +9 -2
index 3f85deb23..8e885af69 100644
@@ -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.
man2/open_by_handle_at.2 +29 -2
index 4061faea9..4cfa21d9c 100644
@@ -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

man2/open_by_handle_at.2 capability. · line 397

Quoted 9 lines
man2/open_by_handle_at.2 +4 -1
@@ -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 aquired using the

This should probably be s/aquired/acquired/

Quoted 14 lines

man2/open_by_handle_at.2 file handles, for example, · line 422

Quoted 11 lines
man2/open_by_handle_at.2 +4 -0
+.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 filesystem support the translation of pathnames to

You should use the plural, filesystems, here.

Fixed in v2.

Thanks for the review!
Amir.