Debian Codegraph @

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

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