[patch] mremap.2: Note/clarify "partial completion" on errors

[patch] mremap.2: Note/clarify "partial completion" on errors

[Keppel, Pardo]

[-- Attachment #1: Type: text/plain, Size: 761 bytes --]

When using mremap() with MREMAP_FIXED and bad parameters, mremap()
returns EINVAL, which is expected; but it also unmaps existing regions
at 'new_address', which surprised me.  I had expected that on EINVAL,
mappings at 'new_address' would remain unmodified.

The current behavior is reasonable, but it was surprising to me, so it might
be surprising to others.  The man page DESCRIPTION currently says:

    "Any previous mapping at the address range specified by new_address
    and new_size is unmapped."

It would be clearer to me if it also said something like:

   "Previous mappings may be unmapped even if mremap() returns an error."

And/or if ERRORS said something about this behavior.

A sample patch for man2/mremap.2 is attached.

[-- Attachment #2: mremap.2.patch --]
[-- Type: application/octet-stream, Size: 788 bytes --]

diff --git a/man2/mremap.2 b/man2/mremap.2
index d73fb64fa..f6408a5c9 100644
--- a/man2/mremap.2
+++ b/man2/mremap.2
@@ -124,6 +124,9 @@ Any previous mapping at the address range specified by
 and
 .I new_size
 is unmapped.
+Previous mappings may be unmapped even if
+.BR mremap ()
+returns an error.
 If
 .B MREMAP_FIXED
 is specified, then
@@ -148,6 +151,16 @@ On error, the value
 (that is, \fI(void\ *)\ \-1\fP) is returned,
 and \fIerrno\fP is set appropriately.
 .SH ERRORS
+On errors,
+.BR mremap ()
+may perform
+.I partial completion
+where some but not all side-effects occur.
+For example, with
+.BR MREMAP_FIXED ,
+mappings at
+.B new_address
+may be unmapped, with no new mappings to replace them.
 .TP
 .B EAGAIN
 The caller tried to expand a memory segment that is locked,