Skip to contentSkip to conversation

MAN: Clarify mremap.2 prototype

PATCH In review Andi Kleen 2 participants 6 messages Jun 3, 2010 – Jun 11, 2010 5 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Andi Kleen

author
#0 lore raw

PATCH 1/1 MAN: Clarify mremap.2 prototype

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/[email protected]>
---
 man2/mremap.2 |    8 ++++++++
 1 file changed, 8 insertions(+)
man2/mremap.2 +8 -0
Index: 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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 20100603090818.GA4741-u0/[email protected]

#2 lore raw
Quoted 35 lines · 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/[email protected]>

---
 man2/mremap.2 |    8 ++++++++

 1 file changed, 8 insertions(+)

Index: man-pages-3.24/man2/mremap.2
===================================================================

man2/mremap.2 +0 -0
@@ -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 ()

man2/mremap.2 +0 -0
@@ -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

man2/mremap.2 +3 -0
+and
+.I MREMAP_MAYMOVE
+are specified. The function is declared in a way that this argument can be omitted.
Quoted 3 lines

 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

man2/mremap.2 +6 -1
index f9d4068..c12ccb2 100644
@@ -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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): AANLkTim4NYbt66oTsxS7ECTzi63gpli6GuSOBgR2ZlR7-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

author
#4 lore raw
Quoted 3 lines

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.

Quoted 1 line

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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 20100610171503.GG19561-u0/[email protected]

#6 lore raw

Hi Andi,

Quoted 6 lines · Andi Kleen
Quoted 3 lines

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.

Quoted 3 lines
Quoted 1 line

The change will be in man-pages-3.25.

How about all the other missing patches?

Getting there...

Thanks,

Michael

Signature · 7 lines
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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): AANLkTiltSNhhRO0wxqLA0nNAPv70LBclMQTVKUXQd5hE-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

author
#8 lore raw
Quoted 5 lines
Quoted 2 lines

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

Signature · 5 lines
ak-VuQAYsv1563Yd54FQh9/[email protected] -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 20100611083810.GG6864-u0/[email protected]

#10 lore raw

Andi,

Quoted 8 lines · Andi Kleen
Quoted 5 lines
Quoted 2 lines

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

man2/mremap.2 +1 -1
@@ -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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html