Debian Bug report logs - #367401
manpages-dev: please make it more clear that MAP_{SHARED,PRIVATE} are the same for a read-only map

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>

To: submit@bugs.debian.org

Subject: manpages-dev: please make mmap.2 reference mincore.2

Date: Mon, 15 May 2006 13:43:50 -0400

Package: manpages-dev
Version: 2.28-1
Severity: wishlist
Tags: patch

changes:
  make mmap.2 reference mincore
  explicitly state that a read-only MAP_PRIVATE is equivalent to
  MAP_SHARED 

An alternative would be to take the commented-out Linus quote embedded
in mmap.2 which says precisely what I want and create a NOTES section
out of it.

--- -	2006-05-12 19:54:03.058873000 -0400
+++ /tmp/mmap.2	2006-05-12 19:51:07.000000000 -0400
@@ -366,6 +366,7 @@
 .BR mmap2 (2),
 .BR mremap (2),
 .BR msync (2),
+.BR mincore (2),
 .BR setrlimit (2),
 .BR shm_open (3)
 .br

--- -	2006-05-13 10:47:59.175369000 -0400
+++ /tmp/mmap.2a	2006-05-13 10:47:19.000000000 -0400
@@ -115,7 +115,8 @@
 .BR mmap ()
 call are visible in the mapped region.
 .LP
-You must specify exactly one of MAP_SHARED and MAP_PRIVATE.
+You must specify exactly one of MAP_SHARED and MAP_PRIVATE (for a
+read-only mapping, they are equivalent).
 .LP
 The above three flags are described in POSIX.1b (formerly POSIX.4) and SUSv2.
 Linux also knows about the following non-standard flags:

Message #10 received at 367401@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Justin Pryzby <justinpryzby@users.sourceforge.net>,367401@bugs.debian.org

Cc: control@bugs.debian.org

Subject: Re: Bug#367401: manpages-dev: please make mmap.2 reference mincore.2

Date: Mon, 15 May 2006 21:52:36 +0200 (MEST)

> changes:
>   make mmap.2 reference mincore

Done, for 2.33.

>   explicitly state that a read-only MAP_PRIVATE is equivalent to
>   MAP_SHARED 

*why?*  You do not explain what benefit this serves.

> An alternative would be to take the commented-out Linus quote embedded
> in mmap.2 which says precisely what I want and create a NOTES section
> out of it.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.

Message #15 received at 367401@bugs.debian.org (full text, mbox, reply):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>

To: Michael Kerrisk <mtk-manpages@gmx.net>

Cc: 367401@bugs.debian.org

Subject: Re: Bug#367401: manpages-dev: please make mmap.2 reference mincore.2

Date: Mon, 15 May 2006 15:59:21 -0400

On Mon, May 15, 2006 at 09:52:36PM +0200, Michael Kerrisk wrote:
> > changes:
> >   make mmap.2 reference mincore
> 
> Done, for 2.33.
> 
> >   explicitly state that a read-only MAP_PRIVATE is equivalent to
> >   MAP_SHARED 
> 
> *why?*  You do not explain what benefit this serves.
Because, upon reflection, it isn't immediately clear from the wording
of the page as it exists now.  In particular:

  Create a  private  copy-on-write  mapping

This could be interpretted as meaning "create a new mapping, even if
the file is already mapped", which isn't what people usually want, and
isn't what it does anyway..

> > An alternative would be to take the commented-out Linus quote embedded
> > in mmap.2 which says precisely what I want and create a NOTES section
> > out of it.

Message #20 received at 367401@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Justin Pryzby <justinpryzby@users.sourceforge.net>

Cc: 367401@bugs.debian.org

Subject: Re: Bug#367401: manpages-dev: please make mmap.2 reference mincore.2

Date: Mon, 15 May 2006 22:06:29 +0200 (MEST)

> > > changes:
> > >   make mmap.2 reference mincore
> > 
> > Done, for 2.33.
> > 
> > >   explicitly state that a read-only MAP_PRIVATE is equivalent to
> > >   MAP_SHARED 
> > 
> > *why?*  You do not explain what benefit this serves.
> Because, upon reflection, it isn't immediately clear from the wording
> of the page as it exists now.  In particular:
> 
>   Create a  private  copy-on-write  mapping

Umm -- we were talking about read-only mappings?

> This could be interpretted as meaning "create a new mapping, even if
> the file is already mapped", which isn't what people usually want, and
> isn't what it does anyway..
>
> > > An alternative would be to take the commented-out Linus quote 
> > > embedded
> > > in mmap.2 which says precisely what I want and create a NOTES section
> > > out of it.

Let me put things another way: why should a programmer care
about whether read-only mappings are done the same way
internally for both MAP_SHARED and MAP_PRIVATE?  Should
this information change how programs are written?  
I can't think of a reason why it should.  And therefore
there seems no reason to mention it in the man page.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.

Message #25 received at 367401@bugs.debian.org (full text, mbox, reply):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>

To: Michael Kerrisk <mtk-manpages@gmx.net>

Cc: 367401@bugs.debian.org

Subject: Re: Bug#367401: manpages-dev: please make mmap.2 reference mincore.2

Date: Tue, 16 May 2006 07:51:29 -0400

On Mon, May 15, 2006 at 10:06:29PM +0200, Michael Kerrisk wrote:
> > > > changes:
> > > >   make mmap.2 reference mincore
> > > 
> > > Done, for 2.33.
> > > 
> > > >   explicitly state that a read-only MAP_PRIVATE is equivalent to
> > > >   MAP_SHARED 
> > > 
> > > *why?*  You do not explain what benefit this serves.
> > Because, upon reflection, it isn't immediately clear from the wording
> > of the page as it exists now.  In particular:
> > 
> >   Create a  private  copy-on-write  mapping
> 
> Umm -- we were talking about read-only mappings?
Yes; I wish to make it clear that, for a read-only map, the behaviour
is the same.

> > This could be interpretted as meaning "create a new mapping, even if
> > the file is already mapped", which isn't what people usually want, and
> > isn't what it does anyway..
> >
> > > > An alternative would be to take the commented-out Linus quote 
> > > > embedded
> > > > in mmap.2 which says precisely what I want and create a NOTES section
> > > > out of it.
> 
> Let me put things another way: why should a programmer care
> about whether read-only mappings are done the same way
> internally for both MAP_SHARED and MAP_PRIVATE?
A programmer should care whether using MAP_PRIVATE uses extra
resources  than a MAP_SHARED (both maps presumably have some
overhead, for the initial mapping and for each additional mapping).  I
question whether this is presently as clear as it should be.

I think it is typical to need to have *some* understanding of a lower
layer interface than one uses directly, even if the full
implementation details are deliberately opaque.

Would it be better to change the descriptions of MAP_{PRIVATE,SHARED}
themselves?  If you think so, I can suggest something.

Justin

Message #32 received at 367401@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Justin Pryzby <justinpryzby@users.sourceforge.net>

Cc: 367401@bugs.debian.org

Subject: Re: Bug#367401: manpages-dev: please make mmap.2 reference mincore.2

Date: Wed, 17 May 2006 00:25:18 +0200 (MEST)

Justin,

> On Mon, May 15, 2006 at 10:06:29PM +0200, Michael Kerrisk wrote:
> > > > > changes:
> > > > >   make mmap.2 reference mincore
> > > > 
> > > > Done, for 2.33.
> > > > 
> > > > >   explicitly state that a read-only MAP_PRIVATE is equivalent to
> > > > >   MAP_SHARED 
> > > > 
> > > > *why?*  You do not explain what benefit this serves.
> > > Because, upon reflection, it isn't immediately clear from the wording
> > > of the page as it exists now.  In particular:
> > > 
> > >   Create a  private  copy-on-write  mapping
> > 
> > Umm -- we were talking about read-only mappings?
> Yes; I wish to make it clear that, for a read-only map, the behaviour
> is the same.
> 
> > > This could be interpretted as meaning "create a new mapping, even if
> > > the file is already mapped", which isn't what people usually want, 
> > > and isn't what it does anyway..
> > >
> > > > > An alternative would be to take the commented-out Linus quote 
> > > > > embedded
> > > > > in mmap.2 which says precisely what I want and create a NOTES
> > > > > section
> > > > > out of it.
> > 
> > Let me put things another way: why should a programmer care
> > about whether read-only mappings are done the same way
> > internally for both MAP_SHARED and MAP_PRIVATE?
> A programmer should care whether using MAP_PRIVATE uses extra
> resources  than a MAP_SHARED (both maps presumably have some
> overhead, for the initial mapping and for each additional mapping).  I
> question whether this is presently as clear as it should be.

But:

-- you have not demonstrated that there is any significant 
   difference?

-- whether there is a difference on other Unix systems
   (if they show different perfomance characteristics,
   then the man-pages should not make recommendations).

> I think it is typical to need to have *some* understanding of a lower
> layer interface than one uses directly, even if the full
> implementation details are deliberately opaque.

I'm interested in specifics at this point.

> Would it be better to change the descriptions of MAP_{PRIVATE,SHARED}
> themselves?  If you think so, I can suggest something.

No, i don't think any change is warranted.

This sounds awfully like another speculative bug report...

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.

Message #37 received at 367401@bugs.debian.org (full text, mbox, reply):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>

To: Michael Kerrisk <mtk-manpages@gmx.net>, 367401@bugs.debian.org

Subject: Re: Bug#367401: manpages-dev: please make mmap.2 reference mincore.2

Date: Wed, 17 May 2006 10:10:39 -0400

On Wed, May 17, 2006 at 12:25:18AM +0200, Michael Kerrisk wrote:
> Justin,
> 
> > On Mon, May 15, 2006 at 10:06:29PM +0200, Michael Kerrisk wrote:
> > > > > > changes:
> > > > > >   make mmap.2 reference mincore
> > > > > 
> > > > > Done, for 2.33.
> > > > > 
> > > > > >   explicitly state that a read-only MAP_PRIVATE is equivalent to
> > > > > >   MAP_SHARED 
> > > > > 
> > > > > *why?*  You do not explain what benefit this serves.
> > > > Because, upon reflection, it isn't immediately clear from the wording
> > > > of the page as it exists now.  In particular:
> > > > 
> > > >   Create a  private  copy-on-write  mapping
> > > 
> > > Umm -- we were talking about read-only mappings?
> > Yes; I wish to make it clear that, for a read-only map, the behaviour
> > is the same.
> > 
> > > > This could be interpretted as meaning "create a new mapping, even if
> > > > the file is already mapped", which isn't what people usually want, 
> > > > and isn't what it does anyway..
> > > >
> > > > > > An alternative would be to take the commented-out Linus quote 
> > > > > > embedded
> > > > > > in mmap.2 which says precisely what I want and create a NOTES
> > > > > > section
> > > > > > out of it.
> > > 
> > > Let me put things another way: why should a programmer care
> > > about whether read-only mappings are done the same way
> > > internally for both MAP_SHARED and MAP_PRIVATE?
> > A programmer should care whether using MAP_PRIVATE uses extra
> > resources  than a MAP_SHARED (both maps presumably have some
> > overhead, for the initial mapping and for each additional mapping).  I
> > question whether this is presently as clear as it should be.
> 
> But:
> 
> -- you have not demonstrated that there is any significant 
>    difference?
Do you mean differences between MAP_{PRIVATE,SHARED}?  It is my
understanding that there is no (behavioural) difference for the case
of a read-only mapping.  But I want this to be more obvious.

> -- whether there is a difference on other Unix systems
>    (if they show different perfomance characteristics,
>    then the man-pages should not make recommendations).
I haven't a clue; but I'm surprised that you think it shouldn't make a
recommendation, instead of documenting the differences.

> > I think it is typical to need to have *some* understanding of a lower
> > layer interface than one uses directly, even if the full
> > implementation details are deliberately opaque.
> 
> I'm interested in specifics at this point.
Knowing that the effect of the two constants is the same for a
read-only case helps me to understand what the difference is for the
writable case.

Justin

Message #42 received at 367401@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Justin Pryzby <justinpryzby@users.sourceforge.net>

Cc: 367401@bugs.debian.org

Subject: Re: Bug#367401: manpages-dev: please make mmap.2 reference mincore.2

Date: Thu, 18 May 2006 00:48:46 +0200 (MEST)

Justin,

> On Wed, May 17, 2006 at 12:25:18AM +0200, Michael Kerrisk wrote:
> > Justin,
> > 
> > > On Mon, May 15, 2006 at 10:06:29PM +0200, Michael Kerrisk wrote:
> > > > > > > changes:
> > > > > > >   make mmap.2 reference mincore
> > > > > > 
> > > > > > Done, for 2.33.
> > > > > > 
> > > > > > >   explicitly state that a read-only MAP_PRIVATE is equivalent
> > > > > > >   to MAP_SHARED 
> > > > > > 
> > > > > > *why?*  You do not explain what benefit this serves.
> > > > > Because, upon reflection, it isn't immediately clear from the
> > > > > wording of the page as it exists now.  In particular:
> > > > > 
> > > > >   Create a  private  copy-on-write  mapping
> > > > 
> > > > Umm -- we were talking about read-only mappings?
> > > Yes; I wish to make it clear that, for a read-only map, the behaviour
> > > is the same.
> > > 
> > > > > This could be interpretted as meaning "create a new mapping, even
> > > > > if the file is already mapped", which isn't what people usually >
> > > > want, and isn't what it does anyway..
> > > > >
> > > > > > > An alternative would be to take the commented-out Linus quote 
> > > > > > > embedded
> > > > > > > in mmap.2 which says precisely what I want and create a NOTES
> > > > > > > section out of it.
> > > > 
> > > > Let me put things another way: why should a programmer care
> > > > about whether read-only mappings are done the same way
> > > > internally for both MAP_SHARED and MAP_PRIVATE?
> > > A programmer should care whether using MAP_PRIVATE uses extra
> > > resources  than a MAP_SHARED (both maps presumably have some
> > > overhead, for the initial mapping and for each additional mapping).  >
> > I
> > > question whether this is presently as clear as it should be.
> > 
> > But:
> > 
> > -- you have not demonstrated that there is any significant 
> >    difference?
> Do you mean differences between MAP_{PRIVATE,SHARED}?  It is my
> understanding that there is no (behavioural) difference for the case
> of a read-only mapping.  But I want this to be more obvious.

You supply absolutely no good reason for doing so.
The fact that things currently happen to be done a certain
way does not mean that it won't change in the future
or be different on other systems.  Therefore, don't
document it, unless there is a compelling reason to do
so -- otherwise it is simply misleading information.

<alert>
You persist in arguing this point, but so far, I have 
seen no evidence that you have a deep understanding 
of mmap(), or what the performance issues are.  
You are wasting my time with too many bogus 
bug reports, and I am beginning to get rather 
irritated by it.  Each time you submit a
false or poorly researched bug report means time taken
away from other work that I do on man-pages.  Of course,
there is another choice: I can ignore your reports.
I don't want to do that -- most of your reports are
useful.  But I do not want to waste time sorting
out the good from the bad.  I want you to do it.
</alert>

> > -- whether there is a difference on other Unix systems
> >    (if they show different perfomance characteristics,
> >    then the man-pages should not make recommendations).
> I haven't a clue; but I'm surprised that you think it shouldn't make a
> recommendation, instead of documenting the differences.

Well, *if* the differnt implementations happen to show different
performance results, then it would be misleading simply
to recomment the route to give best performance on Linux.
Bad for portability...

Enough.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.

Message #47 received at 367401-close@bugs.debian.org (full text, mbox, reply):

From: Martin Schulze <joey@infodrom.org>

To: 367401-close@bugs.debian.org

Subject: Bug#367401: fixed in manpages 2.33-1

Date: Sun, 04 Jun 2006 00:02:13 -0700

Source: manpages
Source-Version: 2.33-1

We believe that the bug you reported is fixed in the latest version of
manpages, which is due to be installed in the Debian FTP archive:

manpages-dev_2.33-1_all.deb
  to pool/main/m/manpages/manpages-dev_2.33-1_all.deb
manpages_2.33-1.diff.gz
  to pool/main/m/manpages/manpages_2.33-1.diff.gz
manpages_2.33-1.dsc
  to pool/main/m/manpages/manpages_2.33-1.dsc
manpages_2.33-1_all.deb
  to pool/main/m/manpages/manpages_2.33-1_all.deb
manpages_2.33.orig.tar.gz
  to pool/main/m/manpages/manpages_2.33.orig.tar.gz



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 367401@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Martin Schulze <joey@infodrom.org> (supplier of updated manpages package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.7
Date: Sun,  4 Jun 2006 08:27:46 +0200
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 2.33-1
Distribution: unstable
Urgency: low
Maintainer: Martin Schulze <joey@debian.org>
Changed-By: Martin Schulze <joey@infodrom.org>
Description: 
 manpages   - Manual pages about using a GNU/Linux system
 manpages-dev - Manual pages about using GNU/Linux for development
Closes: 367401 367667 367667 367671 368994
Changes: 
 manpages (2.33-1) unstable; urgency=low
 .
   * New upstream release
     . Added mincore(2) to SEE ALSO of mmap(2) (closes: Bug#367401)
     . Added SEE ALSO referring to unlocked_stdio.3 to stdio(3) (closes:
       Bug#367667)
     . Removed some functions that don't exist in undocumented(7) (closes:
       Bug#367671)
     . Added SEE ALSO referring to stdio.3 to unlocked_stdio(3) (closes:
       Bug#367667)
   * Added missing define _GNU_SOURCE to assert_perror(3) (closes:
     Bug#368994)
Files: 
 447b619d43eedf215851c827421236fb 584 doc - manpages_2.33-1.dsc
 1296efe5a9c390499461f431abd06bf8 1171288 doc - manpages_2.33.orig.tar.gz
 78f4916ed8da5fb889a569d2b394bbaf 49021 doc - manpages_2.33-1.diff.gz
 d9debb8e6d6b324dc997350a173d3baf 476446 doc important manpages_2.33-1_all.deb
 491aba9513d11577c1750735dbf6ed26 1204924 doc standard manpages-dev_2.33-1_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)

iD8DBQFEgoLFW5ql+IAeqTIRAn8TAJ0dtZklJyDnBFU+CobKIzOEfBkShgCgiVZR
bPvcX83RxMKLnNbowqU9ia8=
=KpJQ
-----END PGP SIGNATURE-----

Send a report that this bug log contains spam.