Re: [PATCH v2 1/2] man/man2/mremap.2: describe multiple mapping move

[Lorenzo Stoakes <lorenzo.stoakes@oracle.com>]

On Mon, Jul 28, 2025 at 10:34:07PM +0200, Jann Horn wrote:
> On Mon, Jul 28, 2025 at 4:05 PM Lorenzo Stoakes
> <lorenzo.stoakes@oracle.com> 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 purely a move, that is old_size is equal to new_size and
> > MREMAP_FIXED is specified.
> >
> > To make things clearer, also describe this 'pure 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 so 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 | 78 ++++++++++++++++++++++++++++++++++++++++-------
> >  1 file changed, 67 insertions(+), 11 deletions(-)
> >
> > diff --git a/man/man2/mremap.2 b/man/man2/mremap.2
> > index 2168ca728..cb3412591 100644
> > --- a/man/man2/mremap.2
> > +++ b/man/man2/mremap.2
> > @@ -25,18 +25,41 @@ moving it at the same time (controlled by the
> >  argument and
> >  the available virtual address space).
> >  .P
> > +Mappings can simply be moved by specifying equal
>
> (Bikeshedding: This "simply" sounds weird to me. If you're trying to
> define a "simple move" with this, the rest of this block is not very
> specific about what exactly that is supposed to be. In my opinion,
> "pure" would also be a nicer word than "simple" if you're looking for
> an expression that means "a move that doesn't do other things".)

Will rephrase, the intent is that I'm saying we can 'simply' perform the
'only move'.

>
> > +.I old_size
> > +and
> > +.I new_size
> > +and specifying
> > +.IR new_address ,
> > +see the description of
> > +.B MREMAP_FIXED
> > +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.
> > +.P
> > +If the operation is not a simple move
> > +then
> > +.I old_size
> > +must span only a single mapping.
>
> I'm reading between the lines that "simple move" is supposed to mean
> "the size is not changing and MREMAP_DONTUNMAP is not set", which then
> implies that in order to actually make anything happen, MREMAP_FIXED
> must be specified?

No, MREMAP_DONTUNMAP can be set, but MREMAP_FIXED must always be set for this to
happen.

Let me rephrase for clarity.

>
> > +.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 +128,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.
>
> This is much clearer to me.

Thanks