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.
Signed-off-by: Peter Xu <peterx@redhat.com>
---
man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++---------------
1 file changed, 24 insertions(+), 19 deletions(-)
diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
index 54b34a1bc..1c554107a 100644
--- a/man/man2const/UFFDIO_API.2const
+++ b/man/man2const/UFFDIO_API.2const
@@ -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
--
2.49.0Hi Peter,
On Mon, May 12, 2025 at 01:19:21PM -0400, Peter Xu wrote:
> 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.
>
> Signed-off-by: Peter Xu <peterx@redhat.com>
> ---
> man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++---------------
> 1 file changed, 24 insertions(+), 19 deletions(-)
>
> diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const
> index 54b34a1bc..1c554107a 100644
> --- a/man/man2const/UFFDIO_API.2const
> +++ b/man/man2const/UFFDIO_API.2const
> @@ -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
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.
> +.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
> If the application sets unsupported feature bits,
> the kernel will zero out the returned
> .I uffdio_api
> --
> 2.49.0
>
--
<https://www.alejandro-colomar.es/>
On Wed, May 14, 2025 at 05:59:48PM +0200, Alejandro Colomar wrote: > > +.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 '.'. This one was overlooked indeed, will fix it. > > $ 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. This was not part of the old text, but sure, will do. Thanks, -- Peter Xu
Hi Peter, On Wed, May 14, 2025 at 01:21:17PM -0400, Peter Xu wrote: > On Wed, May 14, 2025 at 05:59:48PM +0200, Alejandro Colomar wrote: > > > +.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 '.'. > > This one was overlooked indeed, will fix it. Thanks! > > > > $ 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. > > 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 > > Thanks, > > -- > Peter Xu > -- <https://www.alejandro-colomar.es/>
On Mon, May 12, 2025 at 10:19 AM Peter Xu <peterx@redhat.com> wrote: > > 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. > > Signed-off-by: Peter Xu <peterx@redhat.com> > --- > man/man2const/UFFDIO_API.2const | 43 ++++++++++++++++++--------------- > 1 file changed, 24 insertions(+), 19 deletions(-) > > diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const > index 54b34a1bc..1c554107a 100644 > --- a/man/man2const/UFFDIO_API.2const > +++ b/man/man2const/UFFDIO_API.2const > @@ -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 > -- > 2.49.0 > lgtm Reviewed-by: Kyle Huey <khuey@kylehuey.com> Thanks, - Kyle
© 2016 - 2026 Red Hat, Inc.