Bug 19332
Summary: | remove editorializing from malloc man page | ||
---|---|---|---|
Product: | Documentation | Reporter: | landijk-user |
Component: | man-pages | Assignee: | Michael Kerrisk (mtk.manpages) |
Status: | RESOLVED CODE_FIX | ||
Severity: | normal | CC: | mtk.manpages, pasky, vapier |
Priority: | P1 | ||
Hardware: | All | ||
OS: | Linux | ||
Kernel Version: | Subsystem: | ||
Regression: | No | Bisected commit-id: | |
Bug Depends on: | 19382 | ||
Bug Blocks: | |||
Attachments: | clean up paragraph, point to proc(5) |
Description
landijk-user
2010-09-30 00:52:21 UTC
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. 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. 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). Created attachment 32102 [details]
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.
Landijk, That text got in the page before I became maintainer. The only reason it's still there is that I didn't notice it. I agree the tone is entirely wrong, and I accepted your patch pretty much as you gave it, keeping a reference to one of the kernel source files (Documentation/vm/overcommit-accounting). The fix will be in man-pages-3.28. |