| 1 |
.\" Copyright 2016, International Business Machines Corp. |
| 2 |
.\" Copyright 2016, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH UFFDIO_API 2const 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
UFFDIO_API |
| 10 |
\- |
| 11 |
enable operation of the userfaultfd and perform API handshake |
| 12 |
.SH LIBRARY |
| 13 |
Standard C library |
| 14 |
.RI ( libc ,\~ \-lc ) |
| 15 |
.SH SYNOPSIS |
| 16 |
.nf |
| 17 |
.BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD* " constants */" |
| 18 |
.B #include <sys/ioctl.h> |
| 19 |
.P |
| 20 |
.BI "int ioctl(int " fd ", UFFDIO_API, struct uffdio_api *" argp ); |
| 21 |
.P |
| 22 |
.B #include <linux/userfaultfd.h> |
| 23 |
.P |
| 24 |
.fi |
| 25 |
.EX |
| 26 |
.B struct uffdio_api { |
| 27 |
.BR " __u64 api;" " /* Requested API version (input) */" |
| 28 |
.BR " __u64 features;" " /* Requested features (input/output) */" |
| 29 |
.BR " __u64 ioctls;" " /* Available ioctl() operations (output) */" |
| 30 |
.B }; |
| 31 |
.EE |
| 32 |
.SH DESCRIPTION |
| 33 |
Enable operation of the userfaultfd and perform API handshake. |
| 34 |
.P |
| 35 |
The |
| 36 |
.I api |
| 37 |
field denotes the API version requested by the application. |
| 38 |
The kernel verifies that it can support the requested API version, |
| 39 |
and sets the |
| 40 |
.I features |
| 41 |
and |
| 42 |
.I ioctls |
| 43 |
fields to bit masks representing all the available features and the generic |
| 44 |
.BR ioctl (2) |
| 45 |
operations available. |
| 46 |
.P |
| 47 |
Before Linux 4.11, the |
| 48 |
.I features |
| 49 |
field must be initialized to zero before the call to |
| 50 |
.BR UFFDIO_API , |
| 51 |
and zero (i.e., no feature bits) is placed in the |
| 52 |
.I features |
| 53 |
field by the kernel upon return from |
| 54 |
.BR ioctl (2). |
| 55 |
.P |
| 56 |
Since Linux 4.11, |
| 57 |
userfaultfd supports features that need to be enabled explicitly. |
| 58 |
To enable any of the features, |
| 59 |
one needs to set the corresponding feature bits in |
| 60 |
.I features |
| 61 |
when issuing the |
| 62 |
.B UFFDIO_API |
| 63 |
ioctl. |
| 64 |
.P |
| 65 |
For historical reasons, |
| 66 |
a temporary userfaultfd is needed to probe |
| 67 |
what userfaultfd features the kernel supports. |
| 68 |
The application needs to create a temporary userfaultfd, |
| 69 |
issue an |
| 70 |
.B UFFDIO_API |
| 71 |
ioctl with |
| 72 |
.I features |
| 73 |
set to zero. |
| 74 |
After the |
| 75 |
.B UFFDIO_API |
| 76 |
ioctl returns successfully, |
| 77 |
.I features |
| 78 |
should contain all the userfaultfd features that the kernel supports. |
| 79 |
The temporary userfaultfd can be safely closed after the probe. |
| 80 |
.P |
| 81 |
If the application sets unsupported feature bits, |
| 82 |
the kernel will zero out the returned |
| 83 |
.I uffdio_api |
| 84 |
structure and return |
| 85 |
.BR EINVAL . |
| 86 |
.P |
| 87 |
The following feature bits may be set: |
| 88 |
.TP |
| 89 |
.BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)" |
| 90 |
When this feature is enabled, |
| 91 |
the userfaultfd objects associated with a parent process are duplicated |
| 92 |
into the child process during |
| 93 |
.BR fork (2) |
| 94 |
and a |
| 95 |
.B UFFD_EVENT_FORK |
| 96 |
event is delivered to the userfaultfd monitor |
| 97 |
.TP |
| 98 |
.BR UFFD_FEATURE_EVENT_REMAP " (since Linux 4.11)" |
| 99 |
If this feature is enabled, |
| 100 |
when the faulting process invokes |
| 101 |
.BR mremap (2), |
| 102 |
the userfaultfd monitor will receive an event of type |
| 103 |
.BR UFFD_EVENT_REMAP . |
| 104 |
.TP |
| 105 |
.BR UFFD_FEATURE_EVENT_REMOVE " (since Linux 4.11)" |
| 106 |
If this feature is enabled, |
| 107 |
when the faulting process calls |
| 108 |
.BR madvise (2) |
| 109 |
with the |
| 110 |
.B MADV_DONTNEED |
| 111 |
or |
| 112 |
.B MADV_REMOVE |
| 113 |
advice value to free a virtual memory area |
| 114 |
the userfaultfd monitor will receive an event of type |
| 115 |
.BR UFFD_EVENT_REMOVE . |
| 116 |
.TP |
| 117 |
.BR UFFD_FEATURE_EVENT_UNMAP " (since Linux 4.11)" |
| 118 |
If this feature is enabled, |
| 119 |
when the faulting process unmaps virtual memory either explicitly with |
| 120 |
.BR munmap (2), |
| 121 |
or implicitly during either |
| 122 |
.BR mmap (2) |
| 123 |
or |
| 124 |
.BR mremap (2), |
| 125 |
the userfaultfd monitor will receive an event of type |
| 126 |
.BR UFFD_EVENT_UNMAP . |
| 127 |
.TP |
| 128 |
.BR UFFD_FEATURE_MISSING_HUGETLBFS " (since Linux 4.11)" |
| 129 |
If this feature bit is set, |
| 130 |
the kernel supports registering userfaultfd ranges on hugetlbfs |
| 131 |
virtual memory areas |
| 132 |
.TP |
| 133 |
.BR UFFD_FEATURE_MISSING_SHMEM " (since Linux 4.11)" |
| 134 |
If this feature bit is set, |
| 135 |
the kernel supports registering userfaultfd ranges on shared memory areas. |
| 136 |
This includes all kernel shared memory APIs: |
| 137 |
System V shared memory, |
| 138 |
.BR tmpfs (5), |
| 139 |
shared mappings of |
| 140 |
.IR /dev/zero , |
| 141 |
.BR mmap (2) |
| 142 |
with the |
| 143 |
.B MAP_SHARED |
| 144 |
flag set, |
| 145 |
.BR memfd_create (2), |
| 146 |
and so on. |
| 147 |
.TP |
| 148 |
.BR UFFD_FEATURE_SIGBUS " (since Linux 4.14)" |
| 149 |
.\" commit 2d6d6f5a09a96cc1fec7ed992b825e05f64cb50e |
| 150 |
If this feature bit is set, no page-fault events |
| 151 |
.RB ( UFFD_EVENT_PAGEFAULT ) |
| 152 |
will be delivered. |
| 153 |
Instead, a |
| 154 |
.B SIGBUS |
| 155 |
signal will be sent to the faulting process. |
| 156 |
Applications using this |
| 157 |
feature will not require the use of a userfaultfd monitor for processing |
| 158 |
memory accesses to the regions registered with userfaultfd. |
| 159 |
.TP |
| 160 |
.BR UFFD_FEATURE_THREAD_ID " (since Linux 4.14)" |
| 161 |
If this feature bit is set, |
| 162 |
.I uffd_msg.pagefault.feat.ptid |
| 163 |
will be set to the faulted thread ID for each page-fault message. |
| 164 |
.TP |
| 165 |
.BR UFFD_FEATURE_PAGEFAULT_FLAG_WP " (since Linux 5.10)" |
| 166 |
If this feature bit is set, |
| 167 |
userfaultfd supports write-protect faults |
| 168 |
for anonymous memory. |
| 169 |
(Note that shmem / hugetlbfs support |
| 170 |
is indicated by a separate feature.) |
| 171 |
.TP |
| 172 |
.BR UFFD_FEATURE_MINOR_HUGETLBFS " (since Linux 5.13)" |
| 173 |
If this feature bit is set, |
| 174 |
the kernel supports registering userfaultfd ranges |
| 175 |
in minor mode on hugetlbfs-backed memory areas. |
| 176 |
.TP |
| 177 |
.BR UFFD_FEATURE_MINOR_SHMEM " (since Linux 5.14)" |
| 178 |
If this feature bit is set, |
| 179 |
the kernel supports registering userfaultfd ranges |
| 180 |
in minor mode on shmem-backed memory areas. |
| 181 |
.TP |
| 182 |
.BR UFFD_FEATURE_EXACT_ADDRESS " (since Linux 5.18)" |
| 183 |
If this feature bit is set, |
| 184 |
.I uffd_msg.pagefault.address |
| 185 |
will be set to the exact page-fault address that was reported by the hardware, |
| 186 |
and will not mask the offset within the page. |
| 187 |
Note that old Linux versions might indicate the exact address as well, |
| 188 |
even though the feature bit is not set. |
| 189 |
.TP |
| 190 |
.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM " (since Linux 5.19)" |
| 191 |
If this feature bit is set, |
| 192 |
userfaultfd supports write-protect faults |
| 193 |
for hugetlbfs and shmem / tmpfs memory. |
| 194 |
.TP |
| 195 |
.BR UFFD_FEATURE_WP_UNPOPULATED " (since Linux 6.4)" |
| 196 |
If this feature bit is set, |
| 197 |
the kernel will handle anonymous memory the same way as file memory, |
| 198 |
by allowing the user to write-protect unpopulated page table entries. |
| 199 |
.TP |
| 200 |
.BR UFFD_FEATURE_POISON " (since Linux 6.6)" |
| 201 |
If this feature bit is set, |
| 202 |
the kernel supports resolving faults with the |
| 203 |
.B UFFDIO_POISON |
| 204 |
ioctl. |
| 205 |
.TP |
| 206 |
.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)" |
| 207 |
If this feature bit is set, |
| 208 |
the write protection faults would be asynchronously resolved |
| 209 |
by the kernel. |
| 210 |
.TP |
| 211 |
.BR UFFD_FEATURE_MOVE " (since Linux 6.8)" |
| 212 |
If this feature bit is set, |
| 213 |
the kernel supports resolving faults with the |
| 214 |
.B UFFDIO_MOVE |
| 215 |
ioctl. |
| 216 |
.P |
| 217 |
The returned |
| 218 |
.I argp->ioctls |
| 219 |
field can contain the following bits: |
| 220 |
.\" FIXME This user-space API seems not fully polished. Why are there |
| 221 |
.\" not constants defined for each of the bit-mask values listed below? |
| 222 |
.TP |
| 223 |
.B 1 << _UFFDIO_API |
| 224 |
The |
| 225 |
.B UFFDIO_API |
| 226 |
operation is supported. |
| 227 |
.TP |
| 228 |
.B 1 << _UFFDIO_REGISTER |
| 229 |
The |
| 230 |
.B UFFDIO_REGISTER |
| 231 |
operation is supported. |
| 232 |
.TP |
| 233 |
.B 1 << _UFFDIO_UNREGISTER |
| 234 |
The |
| 235 |
.B UFFDIO_UNREGISTER |
| 236 |
operation is supported. |
| 237 |
.SH RETURN VALUE |
| 238 |
On success, |
| 239 |
0 is returned. |
| 240 |
.P |
| 241 |
On error, \-1 is returned and |
| 242 |
.I errno |
| 243 |
is set to indicate the error. |
| 244 |
.SH ERRORS |
| 245 |
.TP |
| 246 |
.B EFAULT |
| 247 |
.I argp |
| 248 |
refers to an address that is outside the calling process's |
| 249 |
accessible address space. |
| 250 |
.TP |
| 251 |
.B EINVAL |
| 252 |
The API version requested in the |
| 253 |
.I api |
| 254 |
field is not supported by this kernel, or the |
| 255 |
.I features |
| 256 |
field passed to the kernel includes feature bits that are not supported |
| 257 |
by the current kernel version. |
| 258 |
.TP |
| 259 |
.B EINVAL |
| 260 |
A previous |
| 261 |
.B UFFDIO_API |
| 262 |
call already enabled one or more features for this userfaultfd. |
| 263 |
Calling |
| 264 |
.B UFFDIO_API |
| 265 |
twice, |
| 266 |
the first time with no features set, |
| 267 |
is explicitly allowed |
| 268 |
as per the two-step feature detection handshake. |
| 269 |
.TP |
| 270 |
.B EPERM |
| 271 |
The |
| 272 |
.B UFFD_FEATURE_EVENT_FORK |
| 273 |
feature was enabled, |
| 274 |
but the calling process doesn't have the |
| 275 |
.B CAP_SYS_PTRACE |
| 276 |
capability. |
| 277 |
.SH STANDARDS |
| 278 |
Linux. |
| 279 |
.SH HISTORY |
| 280 |
Linux 4.3. |
| 281 |
.SH CAVEATS |
| 282 |
If an error occurs, |
| 283 |
the kernel may zero the provided |
| 284 |
.I uffdio_api |
| 285 |
structure. |
| 286 |
The caller should treat its contents as unspecified, |
| 287 |
and reinitialize it before re-attempting another |
| 288 |
.B UFFDIO_API |
| 289 |
call. |
| 290 |
.SH BUGS |
| 291 |
In order to detect available userfault features and |
| 292 |
enable some subset of those features |
| 293 |
the userfaultfd file descriptor must be closed after the first |
| 294 |
.B UFFDIO_API |
| 295 |
operation that queries features availability and reopened before |
| 296 |
the second |
| 297 |
.B UFFDIO_API |
| 298 |
operation that actually enables the desired features. |
| 299 |
.SH EXAMPLES |
| 300 |
See |
| 301 |
.BR userfaultfd (2). |
| 302 |
.SH SEE ALSO |
| 303 |
.BR ioctl (2), |
| 304 |
.BR ioctl_userfaultfd (2), |
| 305 |
.BR mmap (2), |
| 306 |
.BR userfaultfd (2) |
| 307 |
.P |
| 308 |
.I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst |