From: Alejandro Colomar Date: Fri, 14 Jun 2024 17:01:50 +0000 (+0200) Subject: ioctl_userfaultfd.2, UFFDIO_POISON.2const: Split UFFDIO_POISON from ioctl_userfaultfd(2) X-Git-Tag: man-pages-6.9~3^2~1^2~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=44ea7ebf633bfda2d8ee1fb58de2e77cfbcf1e08;p=thirdparty%2Fman-pages.git ioctl_userfaultfd.2, UFFDIO_POISON.2const: Split UFFDIO_POISON from ioctl_userfaultfd(2) Signed-off-by: Alejandro Colomar --- diff --git a/man/man2/ioctl_userfaultfd.2 b/man/man2/ioctl_userfaultfd.2 index ea154ff62..c2fd7cafd 100644 --- a/man/man2/ioctl_userfaultfd.2 +++ b/man/man2/ioctl_userfaultfd.2 @@ -76,113 +76,8 @@ events. .BR UFFDIO_WRITEPROTECT (2const) .TQ .BR UFFDIO_CONTINUE (2const) -.SS UFFDIO_POISON -(Since Linux 6.6.) -Mark an address range as "poisoned". -Future accesses to these addresses will raise a -.B SIGBUS -signal. -Unlike -.B MADV_HWPOISON -this works by installing page table entries, -rather than "really" poisoning the underlying physical pages. -This means it only affects this particular address space. -.P -The -.I argp -argument is a pointer to a -.I uffdio_poison -structure as shown below: -.P -.in +4n -.EX -struct uffdio_poison { - struct uffdio_range range; - /* Range to install poison PTE markers in */ - __u64 mode; /* Flags controlling the behavior of poison */ - __s64 updated; /* Number of bytes poisoned, or negated error */ -}; -.EE -.in -.P -The following value may be bitwise ORed in -.I mode -to change the behavior of the -.B UFFDIO_POISON -operation: -.TP -.B UFFDIO_POISON_MODE_DONTWAKE -Do not wake up the thread that waits for page-fault resolution. -.P -The -.I updated -field is used by the kernel -to return the number of bytes that were actually poisoned, -or an error in the same manner as -.BR UFFDIO_COPY . -If the value returned in the -.I updated -field doesn't match the value that was specified in -.IR range.len , -the operation fails with the error -.BR EAGAIN . -The -.I updated -field is output-only; -it is not read by the -.B UFFDIO_POISON -operation. -.P -This -.BR ioctl (2) -operation returns 0 on success. -In this case, -the entire area was poisoned. -On error, \-1 is returned and -.I errno -is set to indicate the error. -Possible errors include: -.TP -.B EAGAIN -The number of bytes mapped -(i.e., the value returned in the -.I updated -field) -does not equal the value that was specified in the -.I range.len -field. -.TP -.B EINVAL -Either -.I range.start -or -.I range.len -was not a multiple of the system page size; or -.I range.len -was zero; or the range specified was invalid. -.TP -.B EINVAL -An invalid bit was specified in the -.I mode -field. -.TP -.B EEXIST -One or more pages were already mapped in the given range. -.TP -.B ENOENT -The faulting process has changed its virtual memory layout simultaneously with -an outstanding -.B UFFDIO_POISON -operation. -.TP -.B ENOMEM -Allocating memory for page table entries failed. -.TP -.B ESRCH -The faulting process has exited at the time of a -.B UFFDIO_POISON -operation. -.\" +.TQ +.BR UFFDIO_POISON (2const) .SH RETURN VALUE See descriptions of the individual operations, above. .SH ERRORS diff --git a/man/man2const/UFFDIO_POISON.2const b/man/man2const/UFFDIO_POISON.2const new file mode 100644 index 000000000..5b7ca4d35 --- /dev/null +++ b/man/man2const/UFFDIO_POISON.2const @@ -0,0 +1,141 @@ +.\" Copyright 2016, IBM Corporation. +.\" Written by Mike Rapoport +.\" Copyright 2016, Michael Kerrisk +.\" Copyright 2024, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH UFFDIO_POISON 2const (date) "Linux man-pages (unreleased)" +.SH NAME +UFFDIO_POISON +\- +mark an address range as "poisoned" +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " UFFD* " constants */" +.B #include +.P +.BI "int ioctl(int " fd ", UFFDIO_POISON, ...);" +.fi +.SH DESCRIPTION +(Since Linux 6.6.) +Mark an address range as "poisoned". +Future accesses to these addresses will raise a +.B SIGBUS +signal. +Unlike +.B MADV_HWPOISON +this works by installing page table entries, +rather than "really" poisoning the underlying physical pages. +This means it only affects this particular address space. +.P +The +.I argp +argument is a pointer to a +.I uffdio_poison +structure as shown below: +.P +.in +4n +.EX +struct uffdio_poison { + struct uffdio_range range; + /* Range to install poison PTE markers in */ + __u64 mode; /* Flags controlling the behavior of poison */ + __s64 updated; /* Number of bytes poisoned, or negated error */ +}; +.EE +.in +.P +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_POISON +operation: +.TP +.B UFFDIO_POISON_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.P +The +.I updated +field is used by the kernel +to return the number of bytes that were actually poisoned, +or an error in the same manner as +.BR UFFDIO_COPY . +If the value returned in the +.I updated +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I updated +field is output-only; +it is not read by the +.B UFFDIO_POISON +operation. +.SH RETURN VALUE +This +.BR ioctl (2) +operation returns 0 on success. +In this case, +the entire area was poisoned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The number of bytes mapped +(i.e., the value returned in the +.I updated +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B ENOENT +The faulting process has changed its virtual memory layout simultaneously with +an outstanding +.B UFFDIO_POISON +operation. +.TP +.B ENOMEM +Allocating memory for page table entries failed. +.TP +.B ESRCH +The faulting process has exited at the time of a +.B UFFDIO_POISON +operation. +.SH STANDARDS +Linux. +.SH HISTORY +.SH EXAMPLES +See +.BR userfaultfd (2). +.SH SEE ALSO +.BR ioctl (2), +.BR ioctl_userfaultfd (2), +.BR userfaultfd (2) +.P +.I Documentation/admin\-guide/mm/userfaultfd.rst +in the Linux kernel source tree