Debian Codegraph @

upstream/debian-trixie/man2/UFFDIO_COPY.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_COPY 2const 2024-06-17 "Linux man-pages 6.9.1"
9 .SH NAME
10 UFFDIO_COPY
11 \-
12 atomically copy a continuous memory chunk into the userfault registered range
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_COPY, struct uffdio_copy *" argp );
22 .P
23 .B #include <linux/userfaultfd.h>
24 .P
25 .fi
26 .EX
27 .B struct uffdio_copy {
28 .BR " __u64 dst;" " /* Destination of copy */"
29 .BR " __u64 src;" " /* Source of copy */"
30 .BR " __u64 len;" " /* Number of bytes to copy */"
31 .BR " __u64 mode;" " /* Flags controlling behavior of copy */"
32 .BR " __s64 copy;" " /* Number of bytes copied, or negated error */"
33 .B };
34 .EE
35 .SH DESCRIPTION
36 Atomically copy a continuous memory chunk into the userfault registered
37 range and optionally wake up the blocked thread.
38 .P
39 The following value may be bitwise ORed in
40 .I mode
41 to change the behavior of the
42 .B UFFDIO_COPY
43 operation:
44 .TP
45 .B UFFDIO_COPY_MODE_DONTWAKE
46 Do not wake up the thread that waits for page-fault resolution
47 .TP
48 .B UFFDIO_COPY_MODE_WP
49 Copy the page with read-only permission.
50 This allows the user to trap the next write to the page,
51 which will block and generate another write-protect userfault message.
52 This is used only when both
53 .B UFFDIO_REGISTER_MODE_MISSING
54 and
55 .B UFFDIO_REGISTER_MODE_WP
56 modes are enabled for the registered range.
57 .P
58 The
59 .I copy
60 field is used by the kernel to return the number of bytes
61 that was actually copied, or an error (a negated
62 .IR errno -style
63 value).
64 .\" FIXME Above: Why is the 'copy' field used to return error values?
65 .\" This should be explained in the manual page.
66 The
67 .I copy
68 field is output-only;
69 it is not read by the
70 .B UFFDIO_COPY
71 operation.
72 .SH RETURN VALUE
73 On success,
74 0 is returned.
75 In this case, the entire area was copied.
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 copied (i.e., the value returned in the
84 .I copy
85 field)
86 does not equal the value that was specified in the
87 .I len
88 field.
89 .TP
90 .B EINVAL
91 Either
92 .I dst
93 or
94 .I len
95 was not a multiple of the system page size, or the range specified by
96 .I src
97 and
98 .I len
99 or
100 .I dst
101 and
102 .I len
103 was invalid.
104 .TP
105 .B EINVAL
106 An invalid bit was specified in the
107 .I mode
108 field.
109 .TP
110 .BR ENOENT " (since Linux 4.11)"
111 The faulting process has changed
112 its virtual memory layout simultaneously with an outstanding
113 .B UFFDIO_COPY
114 operation.
115 .TP
116 .BR ENOSPC " (from Linux 4.11 until Linux 4.13)"
117 The faulting process has exited at the time of a
118 .B UFFDIO_COPY
119 operation.
120 .TP
121 .BR ESRCH " (since Linux 4.13)"
122 The faulting process has exited at the time of a
123 .B UFFDIO_COPY
124 operation.
125 .SH STANDARDS
126 Linux.
127 .SH HISTORY
128 Linux 4.3.
129 .SH EXAMPLES
130 See
131 .BR userfaultfd (2).
132 .SH SEE ALSO
133 .BR ioctl (2),
134 .BR ioctl_userfaultfd (2),
135 .BR userfaultfd (2)
136 .P
137 .I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst