[Bug 19332] New: remove editorializing from malloc man page

[Bug 19332] New: remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332

           Summary: remove editorializing from malloc man page
           Product: Documentation
           Version: unspecified
          Platform: All
        OS/Version: Linux
              Tree: Mainline
            Status: NEW
          Severity: normal
          Priority: P1
         Component: man-pages
        AssignedTo: documentation_man-pages-ztI5WcYan/vQLgFONoPN62D2FQJk+8+b@public.gmane.org
        ReportedBy: landijk-user-/E1597aS9LQAvxtiuMwx3w@public.gmane.org
        Regression: No


The man page for malloc in release 3.23 of man-pages has this paragraph in a
section titled "BUGS":

-- 

By default, Linux follows an  optimistic  memory  allocation  strategy.
This  means  that  when malloc() returns non-NULL there is no guarantee
that the memory really is available.  This is a  really  bad  bug.   In
case  it  turns  out that the system is out of memory, one or more pro‐
cesses will be killed by the infamous OOM killer.   In  case  Linux  is
employed  under  circumstances where it would be less desirable to sud‐
denly lose some randomly picked processes, and moreover the kernel ver‐
sion  is  sufficiently  recent,  one can switch off this overcommitting
behavior using a command like:

# echo 2 > /proc/sys/vm/overcommit_memory

See also  the  kernel  Documentation  directory,  files  vm/overcommit-
accounting and sysctl/vm.txt.

--

This paragraph has a polemical tone overall.  Rather than explain the issues,
the paragraph simply advocates a position against overcommit.  Note in
particular the following issues:

1.  "This is a really bad bug." -- Overcommit may be a bug in the sense of
nonconformance to a standard, but it is not made clear exactly which standard. 
Clearly it is not a bug in the sense of unintentional behavior.  Whether or not
overcommit is "really bad" depends on facts which the paragraph does not
present.

2.  "...the infamous OOM killer." -- The word "infamous" here serves only as
advocacy, and does not help developers understand the issues involved.

3.  "...less desirable to suddenly lose some randomly picked processes" -- It
is not true that the OOM killer selects processes randomly.

4.  "one can switch off this overcommitting behavior using a command..." -- You
need to know about more than just overcommit_memory if you want to precisely
control overcommit.  You also need to know about the overcommit ratio, as well
as panic_on_oom.  The manual for malloc is not the right place for a proper
treatment of tuning kernel memory management.

I do not wish to engage in a flamewar over overcommit. I am only trying to
improve the documentation, which better serves developers when it sticks to the
facts.  I suggest changing the content to the following:

--

By default, Linux follows an optimistic memory allocation strategy which can
overcommit the available memory.  The overcommit strategy maximizes the use of
available memory, with the tradeoff that when malloc() returns non-NULL there
is no guarantee the memory really is available. In case it turns out that the
system is out of memory, one or more processes will be killed by the OOM
killer. The overcommit behavior is configurable, and processes may be protected
from the OOM killer as needed.  For more information, see the kernel
documentation files vm/overcommit-accounting and sysctl/vm.txt, and the Web
site
http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/s2-proc-pid.html.

--

In the paragraph I claim that "processes may be protected from the OOM killer,"
and what I am referring to is oom_adj/oom_score.  However, I looked in the
overcommit-accounting and sysctl/vm pages, and didn't see anything about
oom_adj or oom_score.

It appears there is no documentation about oom_adj, based on the below bug
filed against Red Hat.

https://bugzilla.redhat.com/show_bug.cgi?id=239313

Red Hat resolved that bug by writing some documentation for their RHEL
distribution. Hence I added a link to Red Hat's documentation at the end of the
paragraph.  I don't know if it is appropriate to link to distribution-specific
docs in a man page, but I see no other available documentation, and the
information in question seems to be applicable to Linux in general.

-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.--
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

[Bug 19332] remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332


Petr Baudis <pasky-AlSwsSmVLrQ@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |pasky-AlSwsSmVLrQ@public.gmane.org




--- Comment #1 from Petr Baudis <pasky-AlSwsSmVLrQ@public.gmane.org>  2010-09-30 08:22:13 ---
I agree that the paragraph should be rewritten; it always strucks me as really
opinionated one as well every time I stumble upon it. Moreover, I'd move it
from section BUGS to section NOTES.

I do not think it is wise to remove the information on how to turn it off,
though - I see no harm in keeping the extra information. There are already
references to more documentation in the manual page; if there is anything extra
in the web page referenced, the information should be added to the kernel
documentation, I think. I think it is wise to avoid web references in general
whenever possible since most URLs actually tend to be quite volatile, and
vendor-specific documentation specifically to avoid any bias, informational or
otherwise.

-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
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

[Bug 19332] remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332


landijk-user-/E1597aS9LQAvxtiuMwx3w@public.gmane.org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Depends on|                            |19382




--- Comment #2 from landijk-user-/E1597aS9LQAvxtiuMwx3w@public.gmane.org  2010-09-30 18:36:01 ---
With regard to removing the instructions on how to disable overcommit, I
thought it would be better to simply direct people to the proper documentation,
so they can understand all the options.  But I'm not an expert in this area, so
I would be glad to put the instructions back in if that's the right thing.

With regard to the link to Red Hat, I think there is no kernel documentation on
oom_adj and oom_score.  If the manual page for malloc is going to discuss the
OOM killer, it ought to at least point to some documentation about how to tune
its behavior.

So I created a new bug for that, and now this bug depends on that one.

-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
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

[Bug 19332] remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332


Bug 19332 depends on bug 19382, which changed state.

Bug 19382 Summary: oom_adj and oom_score are undocumented
https://bugzilla.kernel.org/show_bug.cgi?id=19382

           What    |Old Value                   |New Value
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |INVALID



-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
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

[Bug 19332] remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332


Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org




--- Comment #3 from Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>  2010-09-30 19:01:48 ---
i'd agree with the linking to a diff man page.  proc(5) already has a section
on overcommit_memory.  perhaps that should be extended with the stuff from
malloc(3) and then malloc(3) simply makes an explicit note to also read about
overcommit_memory in proc(5).

-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
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

[Bug 19332] remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332





--- Comment #4 from landijk-user-/E1597aS9LQAvxtiuMwx3w@public.gmane.org  2010-09-30 20:10:11 ---
Created an attachment (id=32102)
 --> (https://bugzilla.kernel.org/attachment.cgi?id=32102)
clean up paragraph, point to proc(5)

Indeed the proc man page has plenty of information about overcommit, and seems
to to be the right place to treat the subject.  This patch:

* removes inflammatory language
* moves the paragraph to the beginning of the notes section
* points the reader to the overcommit_memory and oom_adj sections of proc(5)

It was tested using "man -l" with man version 2.5.7.

-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
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

[Bug 19332] remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332


Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |ASSIGNED
                 CC|                            |mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org




-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
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

[Bug 19332] remove editorializing from malloc man page

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

https://bugzilla.kernel.org/show_bug.cgi?id=19332


Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         AssignedTo|documentation_man-pages@ker |mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
                   |nel-bugs.osdl.org           |




-- 
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching the assignee of the bug.
--
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