[v2,2/3] mremap: Update manual entry

Message ID 20240716224321.2352246-3-hjl.tools@gmail.com
State Superseded
Headers
Series linux: Update the mremap C implementation [BZ #31968] |

Checks

Context Check Description
redhat-pt-bot/TryBot-apply_patch success Patch applied to master at the time it was sent
linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 success Test passed
linaro-tcwg-bot/tcwg_glibc_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_glibc_check--master-arm success Test passed

Commit Message

H.J. Lu July 16, 2024, 10:43 p.m. UTC
  Update mremap manual entry:

1. Change mremap to variadic.
2. Document MREMAP_FIXED and MREMAP_DONTUNMAP.

Signed-off-by: H.J. Lu <hjl.tools@gmail.com>
---
 manual/llio.texi | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)
  

Patch

diff --git a/manual/llio.texi b/manual/llio.texi
index 6f0a48609b..c6f65089ee 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -1892,7 +1892,7 @@  There is no existing mapping in at least part of the given region.
 
 @end deftypefun
 
-@deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag})
+@deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag}, ... /* void *@var{new_address} */)
 @standards{GNU, sys/mman.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 
@@ -1901,12 +1901,39 @@  area. @var{address} and @var{length} must cover a region entirely mapped
 in the same @code{mmap} statement.  A new mapping with the same
 characteristics will be returned with the length @var{new_length}.
 
-One option is possible, @code{MREMAP_MAYMOVE}.  If it is given in
-@var{flags}, the system may remove the existing mapping and create a new
-one of the desired length in another location.
+Possible flags are
 
-The address of the resulting mapping is returned, or @math{-1}.  Possible
-error codes include:
+@table @code
+
+@item MREMAP_MAYMOVE
+If it is given in @var{flags}, the system may remove the existing mapping
+and create a new one of the desired length in another location.
+
+@item MREMAP_FIXED
+If it is given in @var{flags}, @code{mremap} accepts a fifth argument,
+@code{void *new_address}, which specifies a page-aligned address to
+which the mapping must be moved.  Any previous mapping at the address
+range specified by @var{new_address} and @var{new_size} is unmapped.
+
+@code{MREMAP_FIXED} must be used together with @code{MREMAP_MAYMOVE}.
+
+@item MREMAP_DONTUNMAP
+If it is given in @var{flags}, @code{mremap} accepts a fifth argument,
+@code{void *new_address}, which specifies a page-aligned address.  Any
+previous mapping at the address range specified by @var{new_address} and
+@var{new_size} is unmapped.  If @var{new_address} is @code{NULL}, the
+kernel chooses the page-aligned address at which to create the mapping.
+Otherwise, the kernel takes it as a hint about where to place the mapping.
+The mapping at the address range specified by @var{old_address} and
+@var{old_size} isn't unmapped.
+
+@code{MREMAP_DONTUNMAP} must be used together with @code{MREMAP_MAYMOVE}.
+@var{old_size} must be the same as @var{new_size}.
+
+@end table
+
+The address of the resulting mapping is returned, or @code{MAP_FAILED}.
+Possible error codes include:
 
 @table @code
 
@@ -1915,7 +1942,7 @@  There is no existing mapping in at least part of the original region, or
 the region covers two or more distinct mappings.
 
 @item EINVAL
-The address given is misaligned or inappropriate.
+Any arguments are inappropriate, including unknown @var{flags} values.
 
 @item EAGAIN
 The region has pages locked, and if extended it would exceed the