Debian Codegraph @

upstream/debian-unstable/man2/UFFDIO_POISON.2const

raw
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_POISON 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 UFFDIO_POISON
10 \-
11 mark an address range as "poisoned"
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_POISON, ...);"
21 .P
22 .B #include <linux/userfaultfd.h>
23 .P
24 .fi
25 .EX
26 .B struct uffdio_poison {
27 .B " struct uffdio_range range;"
28 /* Range to install poison PTE markers in */
29 .BR " __u64 mode;" " /* Flags controlling the behavior of poison */"
30 .BR " __s64 updated;" " /* Number of bytes poisoned, or negated error */"
31 .B };
32 .EE
33 .SH DESCRIPTION
34 Mark an address range as "poisoned".
35 Future accesses to these addresses will raise a
36 .B SIGBUS
37 signal.
38 Unlike
39 .B MADV_HWPOISON
40 this works by installing page table entries,
41 rather than "really" poisoning the underlying physical pages.
42 This means it only affects this particular address space.
43 .P
44 The following value may be bitwise ORed in
45 .I mode
46 to change the behavior of the
47 .B UFFDIO_POISON
48 operation:
49 .TP
50 .B UFFDIO_POISON_MODE_DONTWAKE
51 Do not wake up the thread that waits for page-fault resolution.
52 .P
53 The
54 .I updated
55 field is used by the kernel
56 to return the number of bytes that were actually poisoned,
57 or an error in the same manner as
58 .BR UFFDIO_COPY .
59 If the value returned in the
60 .I updated
61 field doesn't match the value that was specified in
62 .IR range.len ,
63 the operation fails with the error
64 .BR EAGAIN .
65 The
66 .I updated
67 field is output-only;
68 it is not read by the
69 .B UFFDIO_POISON
70 operation.
71 .SH RETURN VALUE
72 On success,
73 0 is returned.
74 In this case,
75 the entire area was poisoned.
76 .P
77 On error, \-1 is returned and
78 .I errno
79 is set to indicate the error.
80 .SH ERRORS
81 .TP
82 .B EAGAIN
83 The number of bytes mapped
84 (i.e., the value returned in the
85 .I updated
86 field)
87 does not equal the value that was specified in the
88 .I range.len
89 field.
90 .TP
91 .B EINVAL
92 Either
93 .I range.start
94 or
95 .I range.len
96 was not a multiple of the system page size;
97 or
98 .I range.len
99 was zero;
100 or the range specified was invalid.
101 .TP
102 .B EINVAL
103 An invalid bit was specified in the
104 .I mode
105 field.
106 .TP
107 .B EEXIST
108 One or more pages were already mapped in the given range.
109 .TP
110 .B ENOENT
111 The faulting process has changed its virtual memory layout simultaneously with
112 an outstanding
113 .B UFFDIO_POISON
114 operation.
115 .TP
116 .B ENOMEM
117 Allocating memory for page table entries failed.
118 .TP
119 .B ESRCH
120 The faulting process has exited at the time of a
121 .B UFFDIO_POISON
122 operation.
123 .SH STANDARDS
124 Linux.
125 .SH HISTORY
126 Linux 6.6.
127 .SH EXAMPLES
128 See
129 .BR userfaultfd (2).
130 .SH SEE ALSO
131 .BR ioctl (2),
132 .BR ioctl_userfaultfd (2),
133 .BR userfaultfd (2)
134 .P
135 .I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst