Document the new behaviour introduced in Linux 6.17 whereby it is now
possible to move multiple mappings in a single operation, as long as the
operation is simply an MREMAP_FIXED move - that is old_size is equal to
new_size and MREMAP_FIXED is specified.
To make things clearer, also describe this kind of move operation, before
expanding upon it to describe the newly introduced behaviour.
This change also explains the limitations of of this method and the
possibility of partial failure.
Finally, we pluralise language where it makes sense to do so such that the
documentation does not contradict either this new capability nor the
pre-existing edge case.
Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
---
man/man2/mremap.2 | 84 ++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 73 insertions(+), 11 deletions(-)
diff --git a/man/man2/mremap.2 b/man/man2/mremap.2
index 2168ca728..6ba51310c 100644
--- a/man/man2/mremap.2
+++ b/man/man2/mremap.2
@@ -25,18 +25,47 @@ moving it at the same time (controlled by the
argument and
the available virtual address space).
.P
+Mappings can also simply be moved
+(without any resizing)
+by specifying equal
+.I old_size
+and
+.I new_size
+and using the
+.B MREMAP_FIXED
+flag
+(see below).
+Since Linux 6.17,
+while
+.I old_address
+must reside within a mapping,
+.I old_size
+may span multiple mappings
+which do not have to be
+adjacent to one another when
+performing a move like this.
+The
+.B MREMAP_DONTUNMAP
+flag may be specified.
+.P
+If the operation is not
+simply moving mappings,
+then
+.I old_size
+must span only a single mapping.
+.P
.I old_address
-is the old address of the virtual memory block that you
-want to expand (or shrink).
+is the old address of the first virtual memory block that you
+want to expand, shrink, and/or move.
Note that
.I old_address
has to be page aligned.
.I old_size
-is the old size of the
-virtual memory block.
+is the size of the range containing
+virtual memory blocks to be manipulated.
.I new_size
is the requested size of the
-virtual memory block after the resize.
+virtual memory blocks after the resize.
An optional fifth argument,
.IR new_address ,
may be provided; see the description of
@@ -105,13 +134,43 @@ If
is specified, then
.B MREMAP_MAYMOVE
must also be specified.
+.IP
+Since Linux 6.17,
+if
+.I old_size
+is equal to
+.I new_size
+and
+.B MREMAP_FIXED
+is specified, then
+.I old_size
+may span beyond the mapping in which
+.I old_address
+resides.
+In this case,
+gaps between mappings in the original range
+are maintained in the new range.
+The whole operation is performed atomically
+unless an error arises,
+in which case the operation may be partially
+completed,
+that is,
+some mappings may be moved and others not.
+.IP
+
+Moving multiple mappings is not permitted if
+any of those mappings have either
+been registered with
+.BR userfaultfd (2) ,
+or map drivers that
+specify their own custom address mapping logic.
.TP
.BR MREMAP_DONTUNMAP " (since Linux 5.7)"
.\" commit e346b3813067d4b17383f975f197a9aa28a3b077
This flag, which must be used in conjunction with
.BR MREMAP_MAYMOVE ,
-remaps a mapping to a new address but does not unmap the mapping at
-.IR old_address .
+remaps mappings to a new address but does not unmap them
+from their original address.
.IP
The
.B MREMAP_DONTUNMAP
@@ -149,13 +208,13 @@ mapped.
See NOTES for some possible applications of
.BR MREMAP_DONTUNMAP .
.P
-If the memory segment specified by
+If the memory segments specified by
.I old_address
and
.I old_size
-is locked (using
+are locked (using
.BR mlock (2)
-or similar), then this lock is maintained when the segment is
+or similar), then this lock is maintained when the segments are
resized and/or relocated.
As a consequence, the amount of memory locked by the process may change.
.SH RETURN VALUE
@@ -188,7 +247,10 @@ virtual memory address for this process.
You can also get
.B EFAULT
even if there exist mappings that cover the
-whole address space requested, but those mappings are of different types.
+whole address space requested, but those mappings are of different types,
+and the
+.BR mremap ()
+operation being performed does not support this.
.TP
.B EINVAL
An invalid argument was given.
--
2.50.1Hi Lorenzo, Jann, On Tue, Jul 29, 2025 at 02:47:35PM +0100, Lorenzo Stoakes wrote: > Document the new behaviour introduced in Linux 6.17 whereby it is now > possible to move multiple mappings in a single operation, as long as the > operation is simply an MREMAP_FIXED move - that is old_size is equal to > new_size and MREMAP_FIXED is specified. > > To make things clearer, also describe this kind of move operation, before > expanding upon it to describe the newly introduced behaviour. > > This change also explains the limitations of of this method and the > possibility of partial failure. > > Finally, we pluralise language where it makes sense to do so such that the > documentation does not contradict either this new capability nor the > pre-existing edge case. > > Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com> I see some very minor formatting or punctuation issues, but I'll fix them while applying. Jann, do you plan to review this? Have a lovely day! Alex > --- > man/man2/mremap.2 | 84 ++++++++++++++++++++++++++++++++++++++++------- > 1 file changed, 73 insertions(+), 11 deletions(-) > > diff --git a/man/man2/mremap.2 b/man/man2/mremap.2 > index 2168ca728..6ba51310c 100644 > --- a/man/man2/mremap.2 > +++ b/man/man2/mremap.2 > @@ -25,18 +25,47 @@ moving it at the same time (controlled by the > argument and > the available virtual address space). > .P > +Mappings can also simply be moved > +(without any resizing) > +by specifying equal > +.I old_size > +and > +.I new_size > +and using the > +.B MREMAP_FIXED > +flag > +(see below). > +Since Linux 6.17, > +while > +.I old_address > +must reside within a mapping, > +.I old_size > +may span multiple mappings > +which do not have to be > +adjacent to one another when > +performing a move like this. > +The > +.B MREMAP_DONTUNMAP > +flag may be specified. > +.P > +If the operation is not > +simply moving mappings, > +then > +.I old_size > +must span only a single mapping. > +.P > .I old_address > -is the old address of the virtual memory block that you > -want to expand (or shrink). > +is the old address of the first virtual memory block that you > +want to expand, shrink, and/or move. > Note that > .I old_address > has to be page aligned. > .I old_size > -is the old size of the > -virtual memory block. > +is the size of the range containing > +virtual memory blocks to be manipulated. > .I new_size > is the requested size of the > -virtual memory block after the resize. > +virtual memory blocks after the resize. > An optional fifth argument, > .IR new_address , > may be provided; see the description of > @@ -105,13 +134,43 @@ If > is specified, then > .B MREMAP_MAYMOVE > must also be specified. > +.IP > +Since Linux 6.17, > +if > +.I old_size > +is equal to > +.I new_size > +and > +.B MREMAP_FIXED > +is specified, then > +.I old_size > +may span beyond the mapping in which > +.I old_address > +resides. > +In this case, > +gaps between mappings in the original range > +are maintained in the new range. > +The whole operation is performed atomically > +unless an error arises, > +in which case the operation may be partially > +completed, > +that is, > +some mappings may be moved and others not. > +.IP > + > +Moving multiple mappings is not permitted if > +any of those mappings have either > +been registered with > +.BR userfaultfd (2) , > +or map drivers that > +specify their own custom address mapping logic. > .TP > .BR MREMAP_DONTUNMAP " (since Linux 5.7)" > .\" commit e346b3813067d4b17383f975f197a9aa28a3b077 > This flag, which must be used in conjunction with > .BR MREMAP_MAYMOVE , > -remaps a mapping to a new address but does not unmap the mapping at > -.IR old_address . > +remaps mappings to a new address but does not unmap them > +from their original address. > .IP > The > .B MREMAP_DONTUNMAP > @@ -149,13 +208,13 @@ mapped. > See NOTES for some possible applications of > .BR MREMAP_DONTUNMAP . > .P > -If the memory segment specified by > +If the memory segments specified by > .I old_address > and > .I old_size > -is locked (using > +are locked (using > .BR mlock (2) > -or similar), then this lock is maintained when the segment is > +or similar), then this lock is maintained when the segments are > resized and/or relocated. > As a consequence, the amount of memory locked by the process may change. > .SH RETURN VALUE > @@ -188,7 +247,10 @@ virtual memory address for this process. > You can also get > .B EFAULT > even if there exist mappings that cover the > -whole address space requested, but those mappings are of different types. > +whole address space requested, but those mappings are of different types, > +and the > +.BR mremap () > +operation being performed does not support this. > .TP > .B EINVAL > An invalid argument was given. > -- > 2.50.1 -- <https://www.alejandro-colomar.es/>
Hi Lorenzo, On Tue, Jul 29, 2025 at 02:47:35PM +0100, Lorenzo Stoakes wrote: > Document the new behaviour introduced in Linux 6.17 whereby it is now > possible to move multiple mappings in a single operation, as long as the > operation is simply an MREMAP_FIXED move - that is old_size is equal to > new_size and MREMAP_FIXED is specified. > > To make things clearer, also describe this kind of move operation, before > expanding upon it to describe the newly introduced behaviour. > > This change also explains the limitations of of this method and the > possibility of partial failure. > > Finally, we pluralise language where it makes sense to do so such that the > documentation does not contradict either this new capability nor the > pre-existing edge case. > > Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com> Would it be possible to write a small C program that uses this new feature? Cheers, Alex > --- > man/man2/mremap.2 | 84 ++++++++++++++++++++++++++++++++++++++++------- > 1 file changed, 73 insertions(+), 11 deletions(-) > > diff --git a/man/man2/mremap.2 b/man/man2/mremap.2 > index 2168ca728..6ba51310c 100644 > --- a/man/man2/mremap.2 > +++ b/man/man2/mremap.2 > @@ -25,18 +25,47 @@ moving it at the same time (controlled by the > argument and > the available virtual address space). > .P > +Mappings can also simply be moved > +(without any resizing) > +by specifying equal > +.I old_size > +and > +.I new_size > +and using the > +.B MREMAP_FIXED > +flag > +(see below). > +Since Linux 6.17, > +while > +.I old_address > +must reside within a mapping, > +.I old_size > +may span multiple mappings > +which do not have to be > +adjacent to one another when > +performing a move like this. > +The > +.B MREMAP_DONTUNMAP > +flag may be specified. > +.P > +If the operation is not > +simply moving mappings, > +then > +.I old_size > +must span only a single mapping. > +.P > .I old_address > -is the old address of the virtual memory block that you > -want to expand (or shrink). > +is the old address of the first virtual memory block that you > +want to expand, shrink, and/or move. > Note that > .I old_address > has to be page aligned. > .I old_size > -is the old size of the > -virtual memory block. > +is the size of the range containing > +virtual memory blocks to be manipulated. > .I new_size > is the requested size of the > -virtual memory block after the resize. > +virtual memory blocks after the resize. > An optional fifth argument, > .IR new_address , > may be provided; see the description of > @@ -105,13 +134,43 @@ If > is specified, then > .B MREMAP_MAYMOVE > must also be specified. > +.IP > +Since Linux 6.17, > +if > +.I old_size > +is equal to > +.I new_size > +and > +.B MREMAP_FIXED > +is specified, then > +.I old_size > +may span beyond the mapping in which > +.I old_address > +resides. > +In this case, > +gaps between mappings in the original range > +are maintained in the new range. > +The whole operation is performed atomically > +unless an error arises, > +in which case the operation may be partially > +completed, > +that is, > +some mappings may be moved and others not. > +.IP > + > +Moving multiple mappings is not permitted if > +any of those mappings have either > +been registered with > +.BR userfaultfd (2) , > +or map drivers that > +specify their own custom address mapping logic. > .TP > .BR MREMAP_DONTUNMAP " (since Linux 5.7)" > .\" commit e346b3813067d4b17383f975f197a9aa28a3b077 > This flag, which must be used in conjunction with > .BR MREMAP_MAYMOVE , > -remaps a mapping to a new address but does not unmap the mapping at > -.IR old_address . > +remaps mappings to a new address but does not unmap them > +from their original address. > .IP > The > .B MREMAP_DONTUNMAP > @@ -149,13 +208,13 @@ mapped. > See NOTES for some possible applications of > .BR MREMAP_DONTUNMAP . > .P > -If the memory segment specified by > +If the memory segments specified by > .I old_address > and > .I old_size > -is locked (using > +are locked (using > .BR mlock (2) > -or similar), then this lock is maintained when the segment is > +or similar), then this lock is maintained when the segments are > resized and/or relocated. > As a consequence, the amount of memory locked by the process may change. > .SH RETURN VALUE > @@ -188,7 +247,10 @@ virtual memory address for this process. > You can also get > .B EFAULT > even if there exist mappings that cover the > -whole address space requested, but those mappings are of different types. > +whole address space requested, but those mappings are of different types, > +and the > +.BR mremap () > +operation being performed does not support this. > .TP > .B EINVAL > An invalid argument was given. > -- > 2.50.1 -- <https://www.alejandro-colomar.es/>
On Sun, Aug 03, 2025 at 08:47:28AM +0200, Alejandro Colomar wrote: > Would it be possible to write a small C program that uses this new > feature? I could do, but it's an unusual use of mremap() and we don't currently have example C code for the _general_ usage so I wonder if it might be somewhat misleading to have example code only for this? Cheers, Lorenzo
Hi Lorenzo, On Sun, Aug 03, 2025 at 12:15:15PM +0100, Lorenzo Stoakes wrote: > On Sun, Aug 03, 2025 at 08:47:28AM +0200, Alejandro Colomar wrote: > > Would it be possible to write a small C program that uses this new > > feature? > > I could do, but it's an unusual use of mremap() and we don't currently have > example C code for the _general_ usage so I wonder if it might be somewhat > misleading to have example code only for this? I didn't mean for the manual page. It was more for helping review the changes. If it's very small, it would be useful to include it in the commit message. What do you think? Have a lovely day! Alex > > Cheers, Lorenzo -- <https://www.alejandro-colomar.es/>
On Sun, Aug 03, 2025 at 04:17:39PM +0200, Alejandro Colomar wrote: > Hi Lorenzo, > > On Sun, Aug 03, 2025 at 12:15:15PM +0100, Lorenzo Stoakes wrote: > > On Sun, Aug 03, 2025 at 08:47:28AM +0200, Alejandro Colomar wrote: > > > Would it be possible to write a small C program that uses this new > > > feature? > > > > I could do, but it's an unusual use of mremap() and we don't currently have > > example C code for the _general_ usage so I wonder if it might be somewhat > > misleading to have example code only for this? > > I didn't mean for the manual page. It was more for helping review the > changes. If it's very small, it would be useful to include it in the > commit message. What do you think? Ack I can do. In discussion with colleagues I also realise I have to add a little more information to 2/2 as well, so worth a respin anyway. > > > Have a lovely day! > Alex > Cheers, Lorenzo
© 2016 - 2025 Red Hat, Inc.