name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag
PATCH v2 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.
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(-)
man2/fanotify_mark.2 +9 -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.
man2/open_by_handle_at.2 +39 -3
70 lines not on this page · raw message
Signature · 1 line
2.34.1
Hi Amir,
Quoted 7 lines · Amir Goldstein
A flag to indicate that the requested
file_handleis not intended to be used foropen_by_handle_at(2)and may be needed to identify filesystem objects reported in fanotify events.Reviewed-by Jan Kara <[email protected]>Signed-off-by Amir Goldstein <[email protected]>
Patch applied. Thank you and the reviewers!
Cheers,
Alex
Quoted 118 lines
---
Hi Alejandro,
This is a followup on
AT_HANDLE_FIDfeature from v6.5.Thanks,
Amir.Changes from v1:
- Added RVB/ACK
- Spelling fixesman2/fanotify_mark.2 | 11 +++++++++-- man2/open_by_handle_at.2 | 42 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 48 insertions(+), 5 deletions(-)man2/fanotify_mark.2 +9
-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.man2/open_by_handle_at.2 +39
-3@@ -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.
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5