| Message ID | 20250330111643.1405265-1-amir73il@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | name_to_handle_at.2: Document the AT_HANDLE_CONNECTABLE flag | expand |
Hi Amir, On Sun, Mar 30, 2025 at 01:16:43PM +0200, Amir Goldstein wrote: > A flag since v6.13 to indicate that the requested file_handle is > intended to be used for open_by_handle_at(2) to obtain an open file > with a known path. > > Signed-off-by: Amir Goldstein <amir73il@gmail.com> Please add explicit CC tags for everyone CCd. > --- > man/man2/open_by_handle_at.2 | 31 ++++++++++++++++++++++++++++++- > 1 file changed, 30 insertions(+), 1 deletion(-) > > diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2 > index 6b9758d42..ce3a2cec8 100644 > --- a/man/man2/open_by_handle_at.2 > +++ b/man/man2/open_by_handle_at.2 > @@ -127,6 +127,7 @@ The > .I flags > argument is a bit mask constructed by ORing together zero or more of > .BR AT_HANDLE_FID , > +.BR AT_HANDLE_CONNECTABLE, > .BR AT_EMPTY_PATH , > and > .BR AT_SYMLINK_FOLLOW , > @@ -147,6 +148,29 @@ with the returned > .I file_handle > may fail. > .P > +When > +.I flags > +contain the > +.BR AT_HANDLE_CONNECTABLE " (since Linux 6.13)" > +.\" commit a20853ab8296d4a8754482cb5e9adde8ab426a25 > +flag, the caller indicates that the returned > +.I file_handle > +is needed to open a file with known path later, > +so it should be expected that a subsequent call to > +.BR open_by_handle_at () > +with the returned > +.I file_handle > +may fail if the file was moved, > +but otherwise, > +the path of the opened file is expected to be visible > +from the > +.IR /proc/ pid /fd/* Literal parts of a path name should be in italics, but variable parts should be in roman. Thus: .IR /proc/ pid /fd/ * > +magic link. > +This flag can not be used in combination with the flags > +.BR AT_HANDLE_FID , for only two items, we don't need a comma here. It's for three or more items, that Oxford comma applies. > +and Maybe it's better to say 'and/or'? Otherwise, one may wonder if combining with only one of those but not both may be valid? Have a lovely day! Alex > +.BR AT_EMPTY_PATH . > +.P > Together, the > .I pathname > and > @@ -311,7 +335,7 @@ points outside your accessible address space. > .TP > .B EINVAL > .I flags > -includes an invalid bit value. > +includes an invalid bit value or an invalid bit combination. > .TP > .B EINVAL > .I handle\->handle_bytes > @@ -398,6 +422,11 @@ was acquired using the > .B AT_HANDLE_FID > flag and the filesystem does not support > .BR open_by_handle_at (). > +This error can also occur if the > +.I handle > +was acquired using the > +.B AT_HANDLE_CONNECTABLE > +flag and the file was moved to a different parent. > .SH VERSIONS > FreeBSD has a broadly similar pair of system calls in the form of > .BR getfh () > -- > 2.34.1 >
diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2 index 6b9758d42..ce3a2cec8 100644 --- a/man/man2/open_by_handle_at.2 +++ b/man/man2/open_by_handle_at.2 @@ -127,6 +127,7 @@ The .I flags argument is a bit mask constructed by ORing together zero or more of .BR AT_HANDLE_FID , +.BR AT_HANDLE_CONNECTABLE, .BR AT_EMPTY_PATH , and .BR AT_SYMLINK_FOLLOW , @@ -147,6 +148,29 @@ with the returned .I file_handle may fail. .P +When +.I flags +contain the +.BR AT_HANDLE_CONNECTABLE " (since Linux 6.13)" +.\" commit a20853ab8296d4a8754482cb5e9adde8ab426a25 +flag, the caller indicates that the returned +.I file_handle +is needed to open a file with known path later, +so it should be expected that a subsequent call to +.BR open_by_handle_at () +with the returned +.I file_handle +may fail if the file was moved, +but otherwise, +the path of the opened file is expected to be visible +from the +.IR /proc/ pid /fd/* +magic link. +This flag can not be used in combination with the flags +.BR AT_HANDLE_FID , +and +.BR AT_EMPTY_PATH . +.P Together, the .I pathname and @@ -311,7 +335,7 @@ points outside your accessible address space. .TP .B EINVAL .I flags -includes an invalid bit value. +includes an invalid bit value or an invalid bit combination. .TP .B EINVAL .I handle\->handle_bytes @@ -398,6 +422,11 @@ was acquired using the .B AT_HANDLE_FID flag and the filesystem does not support .BR open_by_handle_at (). +This error can also occur if the +.I handle +was acquired using the +.B AT_HANDLE_CONNECTABLE +flag and the file was moved to a different parent. .SH VERSIONS FreeBSD has a broadly similar pair of system calls in the form of .BR getfh ()
A flag since v6.13 to indicate that the requested file_handle is intended to be used for open_by_handle_at(2) to obtain an open file with a known path. Signed-off-by: Amir Goldstein <amir73il@gmail.com> --- man/man2/open_by_handle_at.2 | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-)