[PATCH] MAN: Clarify mremap.2 prototype

[PATCH] MAN: Clarify mremap.2 prototype

[Andi Kleen]

MAN: Clarify mremap.2 prototype

mremap sometimes accepts more arguments and sometimes less.
Clarify this in the prototype and initial description in the manpage.

Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

---
 man2/mremap.2 |    8 ++++++++
 1 file changed, 8 insertions(+)

Index: man-pages-3.24/man2/mremap.2
===================================================================
--- man-pages-3.24.orig/man2/mremap.2
+++ man-pages-3.24/man2/mremap.2
@@ -39,6 +39,9 @@ mremap \- remap a virtual memory address
 .sp
 .BI "void *mremap(void *" old_address ", size_t " old_size ,
 .BI "             size_t " new_size ", int " flags );
+.sp
+.BI "void *mremap(void *" old_address ", size_t " old_size ,
+.BI "             size_t " new_size ", int " flags ", void *" new_address );
 .fi
 .SH DESCRIPTION
 .BR mremap ()
@@ -54,6 +57,11 @@ aligned.
 virtual memory block.
 \fInew_size\fP is the requested size of the
 virtual memory block after the resize.
+\fInew_address\fP is the new address to move the block to. Only valid when
+.I MREMAP_FIXED
+and
+.I MREMAP_MAYMOVE
+are specified. The function is declared in a way that this argument can be omitted.
 
 In Linux the memory is divided into pages.
 A user process has (one or)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MAN: Clarify mremap.2 prototype

[Michael Kerrisk]

On Thu, Jun 3, 2010 at 11:08 AM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> MAN: Clarify mremap.2 prototype
>
> mremap sometimes accepts more arguments and sometimes less.
> Clarify this in the prototype and initial description in the manpage.
>
> Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>
> ---
>  man2/mremap.2 |    8 ++++++++
>  1 file changed, 8 insertions(+)
>
> Index: man-pages-3.24/man2/mremap.2
> ===================================================================
> --- man-pages-3.24.orig/man2/mremap.2
> +++ man-pages-3.24/man2/mremap.2
> @@ -39,6 +39,9 @@ mremap \- remap a virtual memory address
>  .sp
>  .BI "void *mremap(void *" old_address ", size_t " old_size ,
>  .BI "             size_t " new_size ", int " flags );
> +.sp
> +.BI "void *mremap(void *" old_address ", size_t " old_size ,
> +.BI "             size_t " new_size ", int " flags ", void *" new_address );
>  .fi
>  .SH DESCRIPTION
>  .BR mremap ()
> @@ -54,6 +57,11 @@ aligned.
>  virtual memory block.
>  \fInew_size\fP is the requested size of the
>  virtual memory block after the resize.
> +\fInew_address\fP is the new address to move the block to. Only valid when
> +.I MREMAP_FIXED
> +and
> +.I MREMAP_MAYMOVE
> +are specified. The function is declared in a way that this argument can be omitted.
>
>  In Linux the memory is divided into pages.
>  A user process has (one or)
>

Hi Andi,

Thanks for the patch. I agree that mremap() could be improved
somewhat. But note that new_size was already described in the page. I
applied the following simpler patch.

The change will be in man-pages-3.25.

Cheers,

Michael

diff --git a/man2/mremap.2 b/man2/mremap.2
index f9d4068..c12ccb2 100644
--- a/man2/mremap.2
+++ b/man2/mremap.2
@@ -38,7 +38,7 @@ mremap \- remap a virtual memory address
 .B #include <sys/mman.h>
 .sp
 .BI "void *mremap(void *" old_address ", size_t " old_size ,
-.BI "             size_t " new_size ", int " flags );
+.BI "             size_t " new_size ", int " flags ", ...);"
 .fi
 .SH DESCRIPTION
 .BR mremap ()
@@ -54,6 +54,11 @@ aligned.
 virtual memory block.
 \fInew_size\fP is the requested size of the
 virtual memory block after the resize.
+An optional fifth argument,
+.IR new_size ,
+may be provided; see the description of
+.B MREMAP_FIXED
+below.

 In Linux the memory is divided into pages.
 A user process has (one or)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MAN: Clarify mremap.2 prototype

[Andi Kleen]

> Thanks for the patch. I agree that mremap() could be improved
> somewhat. But note that new_size was already described in the page. I
> applied the following simpler patch.

This change will give less information to the reader than the patch. It doesn't 
seem like a improvement to me.

> The change will be in man-pages-3.25.

How about all the other missing patches?

-Andi
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MAN: Clarify mremap.2 prototype

[Michael Kerrisk]

Hi Andi,

On Thu, Jun 10, 2010 at 7:15 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>> Thanks for the patch. I agree that mremap() could be improved
>> somewhat. But note that new_size was already described in the page. I
>> applied the following simpler patch.
>
> This change will give less information to the reader than the patch. It doesn't
> seem like a improvement to me.

It gives less information than your patch, because your patch repeated
information that was already in the page.

>> The change will be in man-pages-3.25.
>
> How about all the other missing patches?

Getting there...

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MAN: Clarify mremap.2 prototype

[Andi Kleen]

> > This change will give less information to the reader than the patch. It doesn't
> > seem like a improvement to me.
> 
> It gives less information than your patch, because your patch repeated
> information that was already in the page.

The correct prototype for the 5 argument option was and is still missing.
Text is no replacement for a correct prototype.

BTW I was prompted to this patch by a real world incident, someone
overlooking the fifth argument.

-Andi

-- 
ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] MAN: Clarify mremap.2 prototype

[Michael Kerrisk]

Andi,

On Fri, Jun 11, 2010 at 10:38 AM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>> > This change will give less information to the reader than the patch. It doesn't
>> > seem like a improvement to me.
>>
>> It gives less information than your patch, because your patch repeated
>> information that was already in the page.
>
> The correct prototype for the 5 argument option was and is still missing.
> Text is no replacement for a correct prototype.

What I want to avoid is cluttering the page with multiple prototypes.
(If we went that way, then pages like fcntl(2) could get rather
messy.) But, to try to alleviate your concern, I modified the patch
somewhat. Hopefully, this will satisfy you.

Cheers,

Michael

--- a/man2/mremap.2
+++ b/man2/mremap.2
@@ -38,7 +38,7 @@ mremap \- remap a virtual memory address
 .B #include <sys/mman.h>
 .sp
 .BI "void *mremap(void *" old_address ", size_t " old_size ,
-.BI "             size_t " new_size ", int " flags );
+.BI "             size_t " new_size ", int " flags ", ... /* void *"
new_address " */);"
 .fi
 .SH DESCRIPTION
 .BR mremap ()
@@ -54,6 +54,11 @@ aligned.
 virtual memory block.
 \fInew_size\fP is the requested size of the
 virtual memory block after the resize.
+An optional fifth argument,
+.IR new_address ,
+may be provided; see the description of
+.B MREMAP_FIXED
+below.

 In Linux the memory is divided into pages.
 A user process has (one or)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html