UFFDIO_API.2const: Two man page updates
cover UFFDIO_API.2const: Two man page updates
The first patch updates the page on two-steps handshake, removing the misleading paragraph and replacing it with a paragraph explaining the correct way to probe the userfaultfd features.
The second patch is a small touch up on the same man page that misses the newly added UFFDIO_MOVE feature.
Thanks,
Peter Xu (2):
UFFDIO_API.2const: Update userfaultfd handshake and feature probe UFFDIO_API.2const: Add an entry for UFFDIO_MOVE
man/man2const/UFFDIO_API.2const | 49 ++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 19 deletions(-)
Signature · 1 line
2.49.0
PATCH 1/2 UFFDIO_API.2const: Update userfaultfd handshake and feature probe
There's a confusing paragraph in the man page on two-steps handshake for userfaultfd UFFDIO_API ioctl. In reality, after a successful UFFDIO_API ioctl, the userfaultfd will be locked up on the features and any further UFFDIO_API on top of an initialized userfaultfd would fail.
Modify the UFFDIO_API(2const) man page to reflect the reality. Instead, add a paragraph explaining the right way to probe userfaultfd features. Add that only after the "Before Linux 4.11" paragraph, as the old kernel doesn't support any feature anyway.
--- man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 19 deletions(-)
man/man2const/UFFDIO_API.2const +24 -19
@@ -42,25 +42,6 @@ fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. .P -Since Linux 4.11, -applications should use the -.I features -field to perform a two-step handshake. -First, -.B UFFDIO_API -is called with the -.I features -field set to zero. -The kernel responds by setting all supported feature bits. -.P -Applications which do not require any specific features -can begin using the userfaultfd immediately. -Applications which do need specific features -should call -.B UFFDIO_API -again with a subset of the reported feature bits set -to enable those features. -.P Before Linux 4.11, the .I features field must be initialized to zero before the call to
@@ -70,6 +51,30 @@ and zero (i.e., no feature bits) is placed in the field by the kernel upon return from .BR ioctl (2). .P +Since Linux 4.11, +userfaultfd supports features that need to be enabled explicitly. +To enable any of the features, +one needs to set the corresponding feature bits in +.I features +when issuing the +.B UFFDIO_API +ioctl. +.P +For historical reasons, +a temporary userfaultfd is needed to probe +what userfaultfd features the kernel supports. +The application needs to create a temporary userfaultfd, +issue an +.B UFFDIO_API +ioctl with +.I features +set to 0. After the +.B UFFDIO_API +ioctl returns successfully, +.I features +should contain all the userfaultfd features that the kernel supports. +The temporary userfaultfd can be safely closed after the probe. +.P If the application sets unsupported feature bits, the kernel will zero out the returned .I uffdio_api
Signature · 1 line
2.49.0
Re: [PATCH 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe
Quoted 78 lines · Peter Xu
There's a confusing paragraph in the man page on two-steps handshake for userfaultfd
UFFDIO_APIioctl. In reality, after a successfulUFFDIO_APIioctl, the userfaultfd will be locked up on the features and any furtherUFFDIO_APIon top of an initialized userfaultfd would fail.Modify the
UFFDIO_API(2const)man page to reflect the reality. Instead, add a paragraph explaining the right way to probe userfaultfd features. Add that only after the "Before Linux 4.11" paragraph, as the old kernel doesn't support any feature anyway.Signed-off-by Peter Xu <[email protected]>--- man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 19 deletions(-)man/man2const/UFFDIO_API.2const +24
-20@@ -42,25 +42,6 @@ fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. .P -Since Linux 4.11, -applications should use the -.I features -field to perform a two-step handshake. -First, -.B UFFDIO_API -is called with the -.I features -field set to zero. -The kernel responds by setting all supported feature bits. -.P -Applications which do not require any specific features -can begin using the userfaultfd immediately. -Applications which do need specific features -should call -.B UFFDIO_API -again with a subset of the reported feature bits set -to enable those features. -.P Before Linux 4.11, the .I features field must be initialized to zero before the call to@@ -70,6 +51,30 @@ and zero (i.e., no feature bits) is placed in the field by the kernel upon return from .BR ioctl (2). .P +Since Linux 4.11, +userfaultfd supports features that need to be enabled explicitly. +To enable any of the features, +one needs to set the corresponding feature bits in +.I features +when issuing the +.B UFFDIO_API +ioctl. +.P +For historical reasons, +a temporary userfaultfd is needed to probe +what userfaultfd features the kernel supports. +The application needs to create a temporary userfaultfd, +issue an +.B UFFDIO_API +ioctl with +.I features +set to 0. After the +.B UFFDIO_API +ioctl returns successfully, +.I features +should contain all the userfaultfd features that the kernel supports. +The temporary userfaultfd can be safely closed after the probe. +.P If the application sets unsupported feature bits, the kernel will zero out the returned .I uffdio_api --
Quoted 2 lines
2.49.0
lgtm
Thanks,
- Kyle
Alejandro Colomar
maintainerRe: [PATCH 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe
In reply to Peter XuHi Peter,
Quoted 57 lines · Peter Xu
There's a confusing paragraph in the man page on two-steps handshake for userfaultfd
UFFDIO_APIioctl. In reality, after a successfulUFFDIO_APIioctl, the userfaultfd will be locked up on the features and any furtherUFFDIO_APIon top of an initialized userfaultfd would fail.Modify the
UFFDIO_API(2const)man page to reflect the reality. Instead, add a paragraph explaining the right way to probe userfaultfd features. Add that only after the "Before Linux 4.11" paragraph, as the old kernel doesn't support any feature anyway.Signed-off-by Peter Xu <[email protected]>--- man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 19 deletions(-)man/man2const/UFFDIO_API.2const +8
-19@@ -42,25 +42,6 @@ fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. .P -Since Linux 4.11, -applications should use the -.I features -field to perform a two-step handshake. -First, -.B UFFDIO_API -is called with the -.I features -field set to zero. -The kernel responds by setting all supported feature bits. -.P -Applications which do not require any specific features -can begin using the userfaultfd immediately. -Applications which do need specific features -should call -.B UFFDIO_API -again with a subset of the reported feature bits set -to enable those features. -.P Before Linux 4.11, the .I features field must be initialized to zero before the call to@@ -70,6 +51,30 @@ and zero (i.e., no feature bits) is placed in the field by the kernel upon return from .BR ioctl (2). .P +Since Linux 4.11, +userfaultfd supports features that need to be enabled explicitly. +To enable any of the features, +one needs to set the corresponding feature bits in +.I features +when issuing the +.B UFFDIO_API +ioctl.
man/man2const/UFFDIO_API.2const and zero (i.e., no feature bits) is placed in the · line 71
Quoted 10 lines
man/man2const/UFFDIO_API.2const +10
-0+.P +For historical reasons, +a temporary userfaultfd is needed to probe +what userfaultfd features the kernel supports. +The application needs to create a temporary userfaultfd, +issue an +.B UFFDIO_API +ioctl with +.I features +set to 0. After the
Please use semantic newlines. Break the line after the '.'.
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, long sentences should be split into lines at
clause breaks (commas, semicolons, colons, and so on), and long
clauses should be split at phrase boundaries. This convention,
sometimes known as "semantic newlines", makes it easier to see
the effect of patches, which often operate at the level of indi‐
vidual sentences, clauses, or phrases.Also, please say "zero" instead of "0", as was in the old paragraph. That will allow git-diff(1) --color-moved to detect some movement of text.
man/man2const/UFFDIO_API.2const and zero (i.e., no feature bits) is placed in the · line 77
Quoted 6 lines
man/man2const/UFFDIO_API.2const +6
-0+.B UFFDIO_API +ioctl returns successfully, +.I features +should contain all the userfaultfd features that the kernel supports. +The temporary userfaultfd can be safely closed after the probe. +.P
Thanks!
Have a lovely day!
Alex
Quoted 6 lines
man/man2const/UFFDIO_API.2const +0
-0If the application sets unsupported feature bits, the kernel will zero out the returned .I uffdio_apiSignature · 1 line
2.49.0
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe
Quoted 4 lines · Alejandro Colomar
Quoted 4 lines
+.P
man/man2const/UFFDIO_API.2const +3
-0+For historical reasons, +a temporary userfaultfd is needed to probe +what userfaultfd features the kernel supports.
Quoted 8 lines
man/man2const/UFFDIO_API.2const and zero (i.e., no feature bits) is placed in the · line 71
Quoted 6 lines
man/man2const/UFFDIO_API.2const +6
-0+The application needs to create a temporary userfaultfd, +issue an +.B UFFDIO_API +ioctl with +.I features +set to 0. After thePlease use semantic newlines. Break the line after the '.'.
This one was overlooked indeed, will fix it.
Quoted 11 lines
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, long sentences should be split into lines at
clause breaks (commas, semicolons, colons, and so on), and long
clauses should be split at phrase boundaries. This convention,
sometimes known as "semantic newlines", makes it easier to see
the effect of patches, which often operate at the level of indi‐
vidual sentences, clauses, or phrases.Quoted 3 lines
Also, please say "zero" instead of "0", as was in the old paragraph. That will allow git-diff(1) --color-moved to detect some movement of text.
This was not part of the old text, but sure, will do.
Thanks,
Signature · 1 line
Peter Xu
Alejandro Colomar
maintainerRe: [PATCH 1/2] UFFDIO_API.2const: Update userfaultfd handshake and feature probe
Hi Peter,
Quoted 14 lines · Peter Xu
Quoted 4 lines · Alejandro Colomar
Quoted 4 lines
+.P
man/man2const/UFFDIO_API.2const +3
-0+For historical reasons, +a temporary userfaultfd is needed to probe +what userfaultfd features the kernel supports.Quoted 8 lines
man/man2const/UFFDIO_API.2const and zero (i.e., no feature bits) is placed in the · line 71
Quoted 6 lines
man/man2const/UFFDIO_API.2const +6
-0+The application needs to create a temporary userfaultfd, +issue an +.B UFFDIO_API +ioctl with +.I features +set to 0. After thePlease use semantic newlines. Break the line after the '.'.
Quoted 1 line
This one was overlooked indeed, will fix it.
Thanks!
Quoted 11 lines
Quoted 11 lines
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p' Use semantic newlines In the source of a manual page, new sentences should be started on new lines, long sentences should be split into lines at clause breaks (commas, semicolons, colons, and so on), and long clauses should be split at phrase boundaries. This convention, sometimes known as "semantic newlines", makes it easier to see the effect of patches, which often operate at the level of indi‐ vidual sentences, clauses, or phrases.
Quoted 5 lines
Quoted 3 lines
Also, please say "zero" instead of "0", as was in the old paragraph. That will allow git-diff(1) --color-moved to detect some movement of text.
This was not part of the old text, but sure, will do.
I know you've completely rewritten the paragraph, but even then, parts of the old text remain (maybe because however you write it, some parts need to be said).
-.I features
-field set to zero.
This part is kept in the new text, even if just by chance, and it might be interesting to see that in git-diff(1) --color-moved.
Have a lovely day!
Alex
Quoted 6 lines
Thanks,
Signature · 1 line
Peter Xu
Signature · 1 line
<https://www.alejandro-colomar.es/>
PATCH 2/2 UFFDIO_API.2const: Add an entry for UFFDIO_MOVE
In reply to Peter XuAdd the entry for UFFDIO_MOVE in UFFDIO_API.
--- man/man2const/UFFDIO_API.2const | 6 ++++++ 1 file changed, 6 insertions(+)
man/man2const/UFFDIO_API.2const +6 -0
@@ -204,6 +204,12 @@ ioctl. If this feature bit is set, the write protection faults would be asynchronously resolved by the kernel. +.TP +.BR UFFD_FEATURE_MOVE " (since Linux 6.8)" +If this feature bit is set, +the kernel supports resolving faults with the +.B UFFDIO_MOVE +ioctl. .P The returned .I argp->ioctls
Signature · 1 line
2.49.0
Re: [PATCH 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_MOVE
Quoted 4 lines · Peter Xu
Add the entry for
UFFDIO_MOVEinUFFDIO_API.Signed-off-by Peter Xu <[email protected]>
Thanks!
Quoted 24 lines
--- man/man2const/UFFDIO_API.2const | 6 ++++++ 1 file changed, 6 insertions(+)man/man2const/UFFDIO_API.2const +6
-1@@ -204,6 +204,12 @@ ioctl. If this feature bit is set, the write protection faults would be asynchronously resolved by the kernel. +.TP +.BR UFFD_FEATURE_MOVE " (since Linux 6.8)" +If this feature bit is set, +the kernel supports resolving faults with the +.B UFFDIO_MOVE +ioctl. .P The returned .I argp->ioctls --2.49.0
Alejandro Colomar
maintainerRe: [PATCH 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_MOVE
In reply to Peter XuHi Peter,
Quoted 3 lines · Peter Xu
Add the entry for
UFFDIO_MOVEinUFFDIO_API.Signed-off-by Peter Xu <[email protected]>
Should we add the following tag?
Also, I think the subject should mention UFFD_FEATURE_MOVE, or at least somewhere in the commit message.
Have a lovely day!
Alex
Quoted 25 lines
--- man/man2const/UFFDIO_API.2const | 6 ++++++ 1 file changed, 6 insertions(+)man/man2const/UFFDIO_API.2const +6
-0@@ -204,6 +204,12 @@ ioctl. If this feature bit is set, the write protection faults would be asynchronously resolved by the kernel. +.TP +.BR UFFD_FEATURE_MOVE " (since Linux 6.8)" +If this feature bit is set, +the kernel supports resolving faults with the +.B UFFDIO_MOVE +ioctl. .P The returned .I argp->ioctlsSignature · 1 line
2.49.0
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_MOVE
Quoted 10 lines · Alejandro Colomar
Hi Peter,
Quoted 3 lines · Peter Xu
Add the entry for
UFFDIO_MOVEinUFFDIO_API.Signed-off-by Peter Xu <[email protected]>Should we add the following tag?
Fixes d7dec35a3b19 (2025-05-01; "man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE")
Sure.
Quoted 3 lines
Also, I think the subject should mention
UFFD_FEATURE_MOVE, or at least somewhere in the commit message.
I'll rename the subject to:
UFFDIO_API.2const: Add an entry for UFFDIO_FEATURE_MOVE
I didn't know we need Fixes for man pages. I'll also attach a fixes for the first patch for commit a252b3345 ("ioctl_userfaultfd.2: Describe two-step feature handshake").
Thanks,
Signature · 1 line
Peter Xu
Alejandro Colomar
maintainerRe: [PATCH 2/2] UFFDIO_API.2const: Add an entry for UFFDIO_MOVE
Hi Peter,
Quoted 15 lines · Peter Xu
Quoted 10 lines · Alejandro Colomar
Hi Peter,
Quoted 3 lines · Peter Xu
Add the entry for
UFFDIO_MOVEinUFFDIO_API.Signed-off-by Peter Xu <[email protected]>Should we add the following tag?
Fixes d7dec35a3b19 (2025-05-01; "man/man2/ioctl_userfaultfd.2, man/man2const/UFFDIO_MOVE.2const: Document UFFDIO_MOVE")Sure.
Quoted 1 line
Quoted 8 lines
Quoted 2 lines
Also, I think the subject should mention
UFFD_FEATURE_MOVE, or at least somewhere in the commit message.I'll rename the subject to:
UFFDIO_API.2const: Add an entry for
UFFDIO_FEATURE_MOVEI didn't know we need Fixes for man pages.
We don't *need* it (as you don't technically need it in any projects), but it's nice to have. :)
Quoted 3 lines
I'll also attach a fixes for
the first patch for commita252b3345("ioctl_userfaultfd.2: Describe two-step feature handshake").
Thanks!
Cheers,
Alex
Quoted 6 lines
Thanks,
Signature · 1 line
Peter Xu
Signature · 1 line
<https://www.alejandro-colomar.es/>