| Message ID | 20230903120433.2605027-1-amir73il@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | name_to_handle_at.2,fanotify_mark.2: Document the AT_HANDLE_FID flag | expand |
On Sun 03-09-23 15:04:33, 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. > > Signed-off-by: Amir Goldstein <amir73il@gmail.com> Looks good to me. Feel free to add: Reviewed-by: Jan Kara <jack@suse.cz> Honza > --- > > 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(-) > > 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..4cfa21d9c 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 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. > -- > 2.34.1 >
On Sun, Sep 03, 2023 at 03:04:33PM +0300, 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. > > Signed-off-by: Amir Goldstein <amir73il@gmail.com> > --- For the content, Acked-by: Christian Brauner <brauner@kernel.org>
Hi, On Sun Sep 3, 2023 at 2:04 PM CEST, 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. > > Signed-off-by: Amir Goldstein <amir73il@gmail.com> > --- > > 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(-) > > 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..4cfa21d9c 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 aquired using the This should probably be s/aquired/acquired/ > +.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. > +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.
On Wed, Sep 6, 2023 at 2:28 AM Tom Schwindl <schwindl@posteo.de> wrote: > > Hi, > > On Sun Sep 3, 2023 at 2:04 PM CEST, 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. > > > > Signed-off-by: Amir Goldstein <amir73il@gmail.com> > > --- > > > > 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(-) > > > > 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..4cfa21d9c 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 aquired using the > > This should probably be s/aquired/acquired/ > > > +.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.
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..4cfa21d9c 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 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.
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. Signed-off-by: Amir Goldstein <amir73il@gmail.com> --- 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(-)