From: Peter Xu Date: Wed, 14 May 2025 17:26:29 +0000 (-0400) Subject: man/man2const/UFFDIO_API.2const: Update userfaultfd handshake and feature probe X-Git-Tag: man-pages-6.15~53 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=6a949e9b08fd1ad4e77584276b9566e45fc07a93;p=thirdparty%2Fman-pages.git man/man2const/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. Fixes: a252b3345 ("ioctl_userfaultfd.2: Describe two-step feature handshake") Reviewed-by: Kyle Huey Signed-off-by: Peter Xu Message-ID: <20250514172630.569788-2-peterx@redhat.com> Signed-off-by: Alejandro Colomar --- diff --git a/man/man2const/UFFDIO_API.2const b/man/man2const/UFFDIO_API.2const index 2f5f7bc17..c1050fad7 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,31 @@ 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 zero. +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