Skip to contentSkip to conversation

man/man2/ioctl_userfaultfd.2, UFFDIO_MOVE.2const: Add UFFDIO_MOVE page

PATCH Superseded Suren Baghdasaryan 2 participants 5 messages Apr 23, 2025

Subsystems (2)
Memory management Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Suren Baghdasaryan

author
#0 lore raw

PATCH 1/1 man/man2/ioctl_userfaultfd.2, UFFDIO_MOVE.2const: Add UFFDIO_MOVE page

Documentation was extracted from the original patch written by Andrea Arcangeli and upstreamed in [1]. Minor edits were made to maintain the same documentation style as other userfaultfd ioctl commands.

[1] <https://lore.kernel.org/all/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>
---
 man/man2/ioctl_userfaultfd.2     |   2 +
 man/man2const/UFFDIO_MOVE.2const | 149 +++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 man/man2const/UFFDIO_MOVE.2const
man/man2/ioctl_userfaultfd.2 +2 -0
index 3cb1b8305..5ec08ca55 100644
@@ -69,6 +69,8 @@ events.
 .TQ
 .BR UFFDIO_COPY (2const)
 .TQ
+.BR UFFDIO_MOVE (2const)
+.TQ
 .BR UFFDIO_ZEROPAGE (2const)
 .TQ
 .BR UFFDIO_WAKE (2const)
man/man2const/UFFDIO_MOVE.2const new file +149 -0

149 lines not on this page · raw message

base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510

Signature · 1 line
2.49.0.805.g082f7c87e0-goog
maintainer
#1 lore raw

Hi Suren,

Quoted 7 lines · Suren Baghdasaryan

Documentation was extracted from the original patch written by Andrea Arcangeli and upstreamed in [1]. Minor edits were made to maintain the same documentation style as other userfaultfd ioctl commands.

[1] <https://lore.kernel.org/all/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

It looks good, but there are a few issues commented below. Thanks for the patch!

Have a lovely day!
Alex

Quoted 25 lines
---
 man/man2/ioctl_userfaultfd.2     |   2 +
 man/man2const/UFFDIO_MOVE.2const | 149 +++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 man/man2const/UFFDIO_MOVE.2const
man/man2/ioctl_userfaultfd.2 +2 -0
index 3cb1b8305..5ec08ca55 100644
@@ -69,6 +69,8 @@ events.
 .TQ
 .BR UFFDIO_COPY (2const)
 .TQ
+.BR UFFDIO_MOVE (2const)
+.TQ
 .BR UFFDIO_ZEROPAGE (2const)
 .TQ
 .BR UFFDIO_WAKE (2const)
man/man2const/UFFDIO_MOVE.2const new file +0 -0
new file mode 100644
index 000000000..ebeefde22

man/man2const/UFFDIO_MOVE.2const line 1

Quoted 1 line
man/man2const/UFFDIO_MOVE.2const new file +1 -0
@@ -0,0 +1,149 @@
+'\" t

This shouldn't be there. There should be a diagnostic from the build system about it being spurious: that line is there only in pages that use tables (.TS/.TE), to let man(1) know that it should invoke tbl(1).

Quoted 17 lines
man/man2const/UFFDIO_MOVE.2const new file +17 -0
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH UFFDIO_MOVE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+UFFDIO_MOVE
+\-
+atomically move a continuous memory chunk into the userfault registered range
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/userfaultfd.h>" "  /* Definition of " UFFD* " constants */"
+.B #include <sys/ioctl.h>
+.P

man/man2const/UFFDIO_MOVE.2const line 28

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.BI "int ioctl(int " fd ", UFFDIO_MOVE, struct uffdio_move *" argp );
+.P
+.B #include <linux/userfaultfd.h>
+.P
+.fi
+.EX
+.B struct uffdio_move {
+.BR "    __u64  dst;" "   /* Destination of move */"
+.BR "    __u64  src;" "   /* Source of move */"
+.BR "    __u64  len;" "   /* Number of bytes to move */"

Are we in time to name this size instead of len? Length usually refers to the number of non-zero characters in a string, while size refers to number of bytes in some object, which is more appropriate in these cases.

If this has already been released in the kernel, don't worry about it, but if it hasn't, maybe we should call it size?

man/man2const/UFFDIO_MOVE.2const line 35

Quoted 7 lines
man/man2const/UFFDIO_MOVE.2const new file +7 -0
+.BR "    __u64  mode;" "  /* Flags controlling behavior of move */"
+.BR "    __s64  move;" "  /* Number of bytes moved, or negated error */"
+.B };
+.EE
+.SH DESCRIPTION
+Atomically move a continuous memory chunk into the userfault registered
+range and optionally wake up the blocked thread.

Please use semantic newlines. In this case, I'd break the line before 'into', and before 'and'.

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
       In the source of a manual page, new sentences should be  started
       on  new  lines,  long  sentences  should  be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and  long
       clauses  should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier  to  see
       the effect of patches, which often operate at the level of indi‐
       vidual sentences, clauses, or phrases.

man/man2const/UFFDIO_MOVE.2const line 38

Quoted 3 lines
man/man2const/UFFDIO_MOVE.2const new file +3 -0
+.P
+The following value may be bitwise ORed in
+.I mode

Please use .mode instead of mode. That makes it more obvious that we're talking about a struct member. I know most pages don't do this, but I'm planning a global change for consistency soon; since this page is new, we can start clean and do it as

.I .mode

This is done in a few cases already in fanotify(7), for example.

Quoted 7 lines
man/man2const/UFFDIO_MOVE.2const new file +7 -0
+to change the behavior of the
+.B UFFDIO_MOVE
+operation:
+.TP
+.B UFFDIO_MOVE_MODE_DONTWAKE
+Do not wake up the thread that waits for page-fault resolution
+.TP

man/man2const/UFFDIO_MOVE.2const line 55

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
+Allow holes in the source virtual range that is being moved.
+When not specified, the holes will result in
+.B ENOENT
+error.
+When specified, the holes will be accounted as successfully
+moved memory. This is mostly useful to move hugepage aligned
+virtual regions without knowing if there are transparent
+hugepages in the regions or not, but preventing the risk of
+having to split the hugepage during the operation.

Please use semantic newlines. In this case, I'd break:

-  after ','
-  after '.'
-  after 'useful'
-  before 'without'
-  after ','
-  after 'of'

man/man2const/UFFDIO_MOVE.2const line 60

Quoted 5 lines
man/man2const/UFFDIO_MOVE.2const new file +5 -0
+.P
+The
+.I move
+field is used by the kernel to return the number of bytes
+that was actually moved, or an error (a negated

I'd break:

-  after 'kernel'
-  after ','
-  before '('

man/man2const/UFFDIO_MOVE.2const line 62

Quoted 2 lines
man/man2const/UFFDIO_MOVE.2const new file +2 -0
+.IR errno -style
+value). The

Always break after '.'

See also: <https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>

Quoted 5 lines
man/man2const/UFFDIO_MOVE.2const new file +5 -0
+.I move
+field is output-only;
+it is not read by the
+.B UFFDIO_MOVE
+operation.

man/man2const/UFFDIO_MOVE.2const line 77

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.P
+The operation may fail for various reasons. Usually, remapping of
+pages that are not exclusive to the given process fail; once KSM
+might deduplicate pages or fork() COW-shares pages during fork()
+with child processes, they are no longer exclusive. Further, the
+kernel might only perform lightweight checks for detecting whether
+the pages are exclusive, and return -EBUSY in case that check fails.
+To make the operation more likely to succeed, KSM should be
+disabled, fork() should be avoided or MADV_DONTFORK should be
+configured for the source VMA before fork().

Please use semantic newlines.

Also, a few things like EBUSY and MADV_DONTFORK should be marked up.

Quoted 45 lines
man/man2const/UFFDIO_MOVE.2const new file +45 -0
+.SH RETURN VALUE
+On success,
+0 is returned.
+In this case, the entire area was moved.
+.P
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The number of bytes moved (i.e., the value returned in the
+.I move
+field)
+does not equal the value that was specified in the
+.I len
+field.
+.TP
+.B EINVAL
+Either
+.I dst
+or
+.I len
+was not a multiple of the system page size, or the range specified by
+.I src
+and
+.I len
+or
+.I dst
+and
+.I len
+was invalid.
+.TP
+.B EINVAL
+An invalid bit was specified in the
+.I mode
+field.
+.TP
+.BR ENOENT
+The source virtual memory range has unmapped holes and
+.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
+is not set.
+.TP
+.BR EEXIST
+The destination virtual memory range is fully or partially

man/man2const/UFFDIO_MOVE.2const line 132

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+mapped.
+.TP
+.BR EBUSY
+The pages in the source virtual memory range are either
+pinned or not exclusive to the process. The kernel might
+only perform lightweight checks for detecting whether the
+pages are exclusive. To make the operation more likely to
+succeed, KSM should be disabled, fork() should be avoided
+or MADV_DONTFORK should be configured for the source virtual
+memory area before fork().

Semantic newlines.

This paragraph is repeating part of the information from the last paragraph in the DESCRIPTION. Do we want to de-duplicate somehow?

man/man2const/UFFDIO_MOVE.2const line 138

Quoted 6 lines
man/man2const/UFFDIO_MOVE.2const new file +6 -0
+.TP
+.BR ENOMEM
+Allocating memory needed for the operation failed.
+.TP
+.BR ESRCH
+The target process has exited at the time of a UFFDIO_MOVE

UFFDIO_MOVE should be bold.

Quoted 16 lines
man/man2const/UFFDIO_MOVE.2const new file +11 -0
+operation.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.8.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_userfaultfd (2),
+.BR userfaultfd (2)
+.P
+.I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst

base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510

Signature · 1 line
2.49.0.805.g082f7c87e0-goog
Signature · 1 line
<https://www.alejandro-colomar.es/>
author
#2 lore raw
Quoted 8 lines · Alejandro Colomar

Hi Suren,

Quoted 4 lines · Suren Baghdasaryan

Documentation was extracted from the original patch written by Andrea Arcangeli and upstreamed in [1]. Minor edits were made to maintain the same documentation style as other userfaultfd ioctl commands.

Quoted 6 lines
Quoted 3 lines

[1] <https://lore.kernel.org/all/[email protected]/>

Signed-off-by Suren Baghdasaryan <[email protected]>

It looks good, but there are a few issues commented below. Thanks for the patch!

Thanks for the feedback. Working on addressing your comments and will post v2 today.

Quoted 261 lines

Have a lovely day!
Alex

Quoted 25 lines
---
 man/man2/ioctl_userfaultfd.2     |   2 +
 man/man2const/UFFDIO_MOVE.2const | 149 +++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 man/man2const/UFFDIO_MOVE.2const
man/man2/ioctl_userfaultfd.2 +2 -0
index 3cb1b8305..5ec08ca55 100644
@@ -69,6 +69,8 @@ events.
 .TQ
 .BR UFFDIO_COPY (2const)
 .TQ
+.BR UFFDIO_MOVE (2const)
+.TQ
 .BR UFFDIO_ZEROPAGE (2const)
 .TQ
 .BR UFFDIO_WAKE (2const)
man/man2const/UFFDIO_MOVE.2const new file +0 -0
new file mode 100644
index 000000000..ebeefde22

man/man2const/UFFDIO_MOVE.2const line 1

Quoted 1 line
man/man2const/UFFDIO_MOVE.2const new file +1 -0
@@ -0,0 +1,149 @@
+'\" t

This shouldn't be there. There should be a diagnostic from the build system about it being spurious: that line is there only in pages that use tables (.TS/.TE), to let man(1) know that it should invoke tbl(1).

Quoted 17 lines
man/man2const/UFFDIO_MOVE.2const new file +17 -0
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH UFFDIO_MOVE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+UFFDIO_MOVE
+\-
+atomically move a continuous memory chunk into the userfault registered range
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/userfaultfd.h>" "  /* Definition of " UFFD* " constants */"
+.B #include <sys/ioctl.h>
+.P

man/man2const/UFFDIO_MOVE.2const line 28

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.BI "int ioctl(int " fd ", UFFDIO_MOVE, struct uffdio_move *" argp );
+.P
+.B #include <linux/userfaultfd.h>
+.P
+.fi
+.EX
+.B struct uffdio_move {
+.BR "    __u64  dst;" "   /* Destination of move */"
+.BR "    __u64  src;" "   /* Source of move */"
+.BR "    __u64  len;" "   /* Number of bytes to move */"

Are we in time to name this size instead of len? Length usually refers to the number of non-zero characters in a string, while size refers to number of bytes in some object, which is more appropriate in these cases.

If this has already been released in the kernel, don't worry about it, but if it hasn't, maybe we should call it size?

man/man2const/UFFDIO_MOVE.2const line 35

Quoted 7 lines
man/man2const/UFFDIO_MOVE.2const new file +7 -0
+.BR "    __u64  mode;" "  /* Flags controlling behavior of move */"
+.BR "    __s64  move;" "  /* Number of bytes moved, or negated error */"
+.B };
+.EE
+.SH DESCRIPTION
+Atomically move a continuous memory chunk into the userfault registered
+range and optionally wake up the blocked thread.

Please use semantic newlines. In this case, I'd break the line before 'into', and before 'and'.

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
       In the source of a manual page, new sentences should be  started
       on  new  lines,  long  sentences  should  be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and  long
       clauses  should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier  to  see
       the effect of patches, which often operate at the level of indi‐
       vidual sentences, clauses, or phrases.

man/man2const/UFFDIO_MOVE.2const line 38

Quoted 3 lines
man/man2const/UFFDIO_MOVE.2const new file +3 -0
+.P
+The following value may be bitwise ORed in
+.I mode

Please use .mode instead of mode. That makes it more obvious that we're talking about a struct member. I know most pages don't do this, but I'm planning a global change for consistency soon; since this page is new, we can start clean and do it as

.I .mode

This is done in a few cases already in fanotify(7), for example.

Quoted 7 lines
man/man2const/UFFDIO_MOVE.2const new file +7 -0
+to change the behavior of the
+.B UFFDIO_MOVE
+operation:
+.TP
+.B UFFDIO_MOVE_MODE_DONTWAKE
+Do not wake up the thread that waits for page-fault resolution
+.TP

man/man2const/UFFDIO_MOVE.2const line 55

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
+Allow holes in the source virtual range that is being moved.
+When not specified, the holes will result in
+.B ENOENT
+error.
+When specified, the holes will be accounted as successfully
+moved memory. This is mostly useful to move hugepage aligned
+virtual regions without knowing if there are transparent
+hugepages in the regions or not, but preventing the risk of
+having to split the hugepage during the operation.

Please use semantic newlines. In this case, I'd break:

(quoted diff) +0 -6
-  after ','
-  after '.'
-  after 'useful'
-  before 'without'
-  after ','
-  after 'of'

man/man2const/UFFDIO_MOVE.2const line 60

Quoted 6 lines
man/man2const/UFFDIO_MOVE.2const new file +5 -0
+.P
+The
+.I move
+field is used by the kernel to return the number of bytes
+that was actually moved, or an error (a negated

I'd break:

(quoted diff) +0 -3
-  after 'kernel'
-  after ','
-  before '('

man/man2const/UFFDIO_MOVE.2const line 62

Quoted 3 lines
man/man2const/UFFDIO_MOVE.2const new file +2 -0
+.IR errno -style
+value). The

Always break after '.'

See also: <https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>

Quoted 5 lines
man/man2const/UFFDIO_MOVE.2const new file +5 -0
+.I move
+field is output-only;
+it is not read by the
+.B UFFDIO_MOVE
+operation.

man/man2const/UFFDIO_MOVE.2const line 77

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.P
+The operation may fail for various reasons. Usually, remapping of
+pages that are not exclusive to the given process fail; once KSM
+might deduplicate pages or fork() COW-shares pages during fork()
+with child processes, they are no longer exclusive. Further, the
+kernel might only perform lightweight checks for detecting whether
+the pages are exclusive, and return -EBUSY in case that check fails.
+To make the operation more likely to succeed, KSM should be
+disabled, fork() should be avoided or MADV_DONTFORK should be
+configured for the source VMA before fork().

Please use semantic newlines.

Also, a few things like EBUSY and MADV_DONTFORK should be marked up.

Quoted 45 lines
man/man2const/UFFDIO_MOVE.2const new file +45 -0
+.SH RETURN VALUE
+On success,
+0 is returned.
+In this case, the entire area was moved.
+.P
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The number of bytes moved (i.e., the value returned in the
+.I move
+field)
+does not equal the value that was specified in the
+.I len
+field.
+.TP
+.B EINVAL
+Either
+.I dst
+or
+.I len
+was not a multiple of the system page size, or the range specified by
+.I src
+and
+.I len
+or
+.I dst
+and
+.I len
+was invalid.
+.TP
+.B EINVAL
+An invalid bit was specified in the
+.I mode
+field.
+.TP
+.BR ENOENT
+The source virtual memory range has unmapped holes and
+.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
+is not set.
+.TP
+.BR EEXIST
+The destination virtual memory range is fully or partially

man/man2const/UFFDIO_MOVE.2const line 132

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+mapped.
+.TP
+.BR EBUSY
+The pages in the source virtual memory range are either
+pinned or not exclusive to the process. The kernel might
+only perform lightweight checks for detecting whether the
+pages are exclusive. To make the operation more likely to
+succeed, KSM should be disabled, fork() should be avoided
+or MADV_DONTFORK should be configured for the source virtual
+memory area before fork().

Semantic newlines.

This paragraph is repeating part of the information from the last paragraph in the DESCRIPTION. Do we want to de-duplicate somehow?

man/man2const/UFFDIO_MOVE.2const line 138

Quoted 6 lines
man/man2const/UFFDIO_MOVE.2const new file +6 -0
+.TP
+.BR ENOMEM
+Allocating memory needed for the operation failed.
+.TP
+.BR ESRCH
+The target process has exited at the time of a UFFDIO_MOVE

UFFDIO_MOVE should be bold.

Quoted 12 lines
man/man2const/UFFDIO_MOVE.2const new file +11 -0
+operation.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.8.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_userfaultfd (2),
+.BR userfaultfd (2)
+.P
+.I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst
Quoted 4 lines

base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510 --
2.49.0.805.g082f7c87e0-goog

--
<https://www.alejandro-colomar.es/>

author
#3 lore raw
Quoted 12 lines · Suren Baghdasaryan
Quoted 10 lines · Alejandro Colomar

Hi Suren,

Quoted 6 lines · Suren Baghdasaryan

Documentation was extracted from the original patch written by Andrea Arcangeli and upstreamed in [1]. Minor edits were made to maintain the same documentation style as other userfaultfd ioctl commands.

[1] <https://lore.kernel.org/all/[email protected]/>

Quoted 7 lines
Quoted 4 lines
Quoted 1 line
Signed-off-by Suren Baghdasaryan <[email protected]>

It looks good, but there are a few issues commented below. Thanks for the patch!

Thanks for the feedback. Working on addressing your comments and will post v2 today.

Answers to your comments are below.
Resulting v2 is posted at
https://lore.kernel.org/all/[email protected]/
Thanks!

Quoted 28 lines
Quoted 28 lines

Have a lovely day!
Alex

Quoted 22 lines
---
 man/man2/ioctl_userfaultfd.2     |   2 +
 man/man2const/UFFDIO_MOVE.2const | 149 +++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 man/man2const/UFFDIO_MOVE.2const
man/man2/ioctl_userfaultfd.2 +2 -0
index 3cb1b8305..5ec08ca55 100644
@@ -69,6 +69,8 @@ events.
 .TQ
 .BR UFFDIO_COPY (2const)
 .TQ
+.BR UFFDIO_MOVE (2const)
+.TQ
 .BR UFFDIO_ZEROPAGE (2const)
 .TQ
 .BR UFFDIO_WAKE (2const)
man/man2const/UFFDIO_MOVE.2const new file +0 -0
new file mode 100644
index 000000000..ebeefde22
Quoted 8 lines
Quoted 8 lines

man/man2const/UFFDIO_MOVE.2const line 1

Quoted 4 lines
man/man2const/UFFDIO_MOVE.2const new file +1 -0
@@ -0,0 +1,149 @@
+'\" t

This shouldn't be there. There should be a diagnostic from the build system about it being spurious: that line is there only in pages that use tables (.TS/.TE), to let man(1) know that it should invoke tbl(1).

Ack.

Quoted 34 lines
Quoted 34 lines
Quoted 18 lines
man/man2const/UFFDIO_MOVE.2const new file +17 -0
+.\" Written by Andrea Arcangeli <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH UFFDIO_MOVE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+UFFDIO_MOVE
+\-
+atomically move a continuous memory chunk into the userfault registered range
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/userfaultfd.h>" "  /* Definition of " UFFD* " constants */"
+.B #include <sys/ioctl.h>
+.P

man/man2const/UFFDIO_MOVE.2const line 28

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.BI "int ioctl(int " fd ", UFFDIO_MOVE, struct uffdio_move *" argp );
+.P
+.B #include <linux/userfaultfd.h>
+.P
+.fi
+.EX
+.B struct uffdio_move {
+.BR "    __u64  dst;" "   /* Destination of move */"
+.BR "    __u64  src;" "   /* Source of move */"
+.BR "    __u64  len;" "   /* Number of bytes to move */"

Are we in time to name this size instead of len? Length usually refers to the number of non-zero characters in a string, while size refers to number of bytes in some object, which is more appropriate in these cases.

Quoted 2 lines
Quoted 2 lines

If this has already been released in the kernel, don't worry about it, but if it hasn't, maybe we should call it size?

Sorry, it was released back in 6.8.

Quoted 11 lines
Quoted 11 lines

man/man2const/UFFDIO_MOVE.2const line 35

Quoted 8 lines
man/man2const/UFFDIO_MOVE.2const new file +7 -0
+.BR "    __u64  mode;" "  /* Flags controlling behavior of move */"
+.BR "    __s64  move;" "  /* Number of bytes moved, or negated error */"
+.B };
+.EE
+.SH DESCRIPTION
+Atomically move a continuous memory chunk into the userfault registered
+range and optionally wake up the blocked thread.

Please use semantic newlines. In this case, I'd break the line before 'into', and before 'and'.

Ack.

Quoted 15 lines
Quoted 15 lines
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
       In the source of a manual page, new sentences should be  started
       on  new  lines,  long  sentences  should  be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and  long
       clauses  should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier  to  see
       the effect of patches, which often operate at the level of indi‐
       vidual sentences, clauses, or phrases.
Quoted 3 lines
man/man2const/UFFDIO_MOVE.2const new file +3 -0
+.P
+The following value may be bitwise ORed in
+.I mode
Quoted 8 lines
Quoted 8 lines

Please use .mode instead of mode. That makes it more obvious that we're talking about a struct member. I know most pages don't do this, but I'm planning a global change for consistency soon; since this page is new, we can start clean and do it as

.I .mode

This is done in a few cases already in fanotify(7), for example.

Ack. I assume that should be done everywhere else.

Quoted 21 lines
Quoted 21 lines
Quoted 8 lines
man/man2const/UFFDIO_MOVE.2const new file +7 -0
+to change the behavior of the
+.B UFFDIO_MOVE
+operation:
+.TP
+.B UFFDIO_MOVE_MODE_DONTWAKE
+Do not wake up the thread that waits for page-fault resolution
+.TP

man/man2const/UFFDIO_MOVE.2const line 55

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
+Allow holes in the source virtual range that is being moved.
+When not specified, the holes will result in
+.B ENOENT
+error.
+When specified, the holes will be accounted as successfully
+moved memory. This is mostly useful to move hugepage aligned
+virtual regions without knowing if there are transparent
+hugepages in the regions or not, but preventing the risk of
+having to split the hugepage during the operation.

Please use semantic newlines. In this case, I'd break:

Quoted 6 lines

Review

Quoted 6 lines
(quoted diff) +0 -6
-  after ','
-  after '.'
-  after 'useful'
-  before 'without'
-  after ','
-  after 'of'

Ack.

Quoted 9 lines
Quoted 9 lines

man/man2const/UFFDIO_MOVE.2const line 60

Quoted 6 lines
man/man2const/UFFDIO_MOVE.2const new file +5 -0
+.P
+The
+.I move
+field is used by the kernel to return the number of bytes
+that was actually moved, or an error (a negated

I'd break:

Quoted 3 lines

Review

Quoted 3 lines
(quoted diff) +0 -3
-  after 'kernel'
-  after ','
-  before '('

Ack.

Quoted 5 lines
Quoted 5 lines

man/man2const/UFFDIO_MOVE.2const line 62

Quoted 3 lines
man/man2const/UFFDIO_MOVE.2const new file +2 -0
+.IR errno -style
+value). The

Always break after '.'

Ack.

Quoted 21 lines
Quoted 21 lines

See also: <https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>

Quoted 5 lines
man/man2const/UFFDIO_MOVE.2const new file +5 -0
+.I move
+field is output-only;
+it is not read by the
+.B UFFDIO_MOVE
+operation.

man/man2const/UFFDIO_MOVE.2const line 77

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+.P
+The operation may fail for various reasons. Usually, remapping of
+pages that are not exclusive to the given process fail; once KSM
+might deduplicate pages or fork() COW-shares pages during fork()
+with child processes, they are no longer exclusive. Further, the
+kernel might only perform lightweight checks for detecting whether
+the pages are exclusive, and return -EBUSY in case that check fails.
+To make the operation more likely to succeed, KSM should be
+disabled, fork() should be avoided or MADV_DONTFORK should be
+configured for the source VMA before fork().

Please use semantic newlines.

Quoted 1 line
Quoted 1 line

Also, a few things like EBUSY and MADV_DONTFORK should be marked up.

Ack.

Quoted 59 lines
Quoted 59 lines
Quoted 46 lines
man/man2const/UFFDIO_MOVE.2const new file +45 -0
+.SH RETURN VALUE
+On success,
+0 is returned.
+In this case, the entire area was moved.
+.P
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The number of bytes moved (i.e., the value returned in the
+.I move
+field)
+does not equal the value that was specified in the
+.I len
+field.
+.TP
+.B EINVAL
+Either
+.I dst
+or
+.I len
+was not a multiple of the system page size, or the range specified by
+.I src
+and
+.I len
+or
+.I dst
+and
+.I len
+was invalid.
+.TP
+.B EINVAL
+An invalid bit was specified in the
+.I mode
+field.
+.TP
+.BR ENOENT
+The source virtual memory range has unmapped holes and
+.B UFFDIO_MOVE_MODE_ALLOW_SRC_HOLES
+is not set.
+.TP
+.BR EEXIST
+The destination virtual memory range is fully or partially

man/man2const/UFFDIO_MOVE.2const line 132

Quoted 10 lines
man/man2const/UFFDIO_MOVE.2const new file +10 -0
+mapped.
+.TP
+.BR EBUSY
+The pages in the source virtual memory range are either
+pinned or not exclusive to the process. The kernel might
+only perform lightweight checks for detecting whether the
+pages are exclusive. To make the operation more likely to
+succeed, KSM should be disabled, fork() should be avoided
+or MADV_DONTFORK should be configured for the source virtual
+memory area before fork().

Semantic newlines.

Quoted 2 lines
Quoted 2 lines

This paragraph is repeating part of the information from the last paragraph in the DESCRIPTION. Do we want to de-duplicate somehow?

Yes, I folded this into the appropriate error code description.

Quoted 9 lines
Quoted 9 lines

man/man2const/UFFDIO_MOVE.2const line 138

Quoted 7 lines
man/man2const/UFFDIO_MOVE.2const new file +6 -0
+.TP
+.BR ENOMEM
+Allocating memory needed for the operation failed.
+.TP
+.BR ESRCH
+The target process has exited at the time of a UFFDIO_MOVE

UFFDIO_MOVE should be bold.

Ack.

Quoted 20 lines
Quoted 20 lines
Quoted 13 lines
man/man2const/UFFDIO_MOVE.2const new file +11 -0
+operation.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.8.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_userfaultfd (2),
+.BR userfaultfd (2)
+.P
+.I linux.git/\:Documentation/\:admin\-guide/\:mm/\:userfaultfd.rst
Quoted 4 lines

base-commit: 80e2715270fc05d5627c26f88e4c1ba8b093f510 --
2.49.0.805.g082f7c87e0-goog

--
<https://www.alejandro-colomar.es/>

maintainer
#4 lore raw

Hi Suren,

Quoted 10 lines · Suren Baghdasaryan
Quoted 10 lines
Quoted 10 lines
Quoted 4 lines

+.B struct uffdio_move {

+.BR "    __u64  dst;" "   /* Destination of move */"
+.BR "    __u64  src;" "   /* Source of move */"
+.BR "    __u64  len;" "   /* Number of bytes to move */"

Are we in time to name this size instead of len? Length usually refers to the number of non-zero characters in a string, while size refers to number of bytes in some object, which is more appropriate in these cases.

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

If this has already been released in the kernel, don't worry about it, but if it hasn't, maybe we should call it size?

Sorry, it was released back in 6.8.

Okay, no problem.

Quoted 9 lines
Quoted 9 lines
Quoted 9 lines
Quoted 3 lines

+.P
+The following value may be bitwise ORed in
+.I mode

Please use .mode instead of mode. That makes it more obvious that we're talking about a struct member. I know most pages don't do this, but I'm planning a global change for consistency soon; since this page is new, we can start clean and do it as

Quoted 5 lines
Quoted 3 lines
Quoted 3 lines

.I .mode

This is done in a few cases already in fanotify(7), for example.

Ack. I assume that should be done everywhere else.

Yep.

Have a lovely night!
Alex

Signature · 1 line
<https://www.alejandro-colomar.es/>