name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag
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
@@ -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
Quoted 5 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.Signed-off-by Amir Goldstein <[email protected]>
Looks good to me. Feel free to add:
Honza
Quoted 117 lines
---
Hi Alejandro,
This is a followup on
AT_HANDLE_FIDfeature 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@@ -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 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
Quoted 6 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.Signed-off-by Amir Goldstein <[email protected]>---
For the content,
Hi,
Quoted 94 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.Signed-off-by Amir Goldstein <[email protected]>---
Hi Alejandro,
This is a followup on
AT_HANDLE_FIDfeature 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@@ -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@@ -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.
Quoted 110 lines · Tom Schwindl
Hi,
Quoted 94 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.Signed-off-by Amir Goldstein <[email protected]>---
Hi Alejandro,
This is a followup on
AT_HANDLE_FIDfeature 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@@ -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@@ -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 andman2/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 theThis 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 toYou should use the plural, filesystems, here.
Fixed in v2.
Thanks for the review!
Amir.