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@xxxxxxxxxxxxxxxxxxxx ReportedBy: landijk-user@xxxxxxxxx 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
