Update/kill Documentation/sysctl/* docs?
RFC 1/1 Update/kill Documentation/sysctl/* docs?
In http://bugzilla.kernel.org/show_bug.cgi?id=6145 you asked to update the sysctl docs. I've updated them and added/deleted the neccesary stuff (except the ones that I don't know what on earth are they doing because they're not...documented). However it looks like there's duplication - Documentation/filesystems/proc.txt seems to document all that aswell (but in a single doc, which makes it a bit unreadable for such big document, IMO)
What should be the best step? Kill Documentation/sysctl/ and keep filesystems/proc.txt updated and maybe split it in several files to make it more readable? Update it but maintain in sync with filesystems/proc.txt? delete proc.txt and keep sysctl/ updated...?
Documentation/sysctl/fs.txt renamed from Documentation/sysctl/fs.txt.old +45 -27
@@ -1,4 +1,4 @@ -Documentation for /proc/sys/fs/* kernel version 2.2.10 +Documentation for /proc/sys/fs/* (c) 1998, 1999, Rik van Riel <[email protected]> For general info and legal blurb, please look in README.
@@ -6,7 +6,7 @@ ============================================================== This file contains documentation for the sysctl files in -/proc/sys/fs/ and is valid for Linux kernel version 2.2. +/proc/sys/fs/ The files in this directory can be used to tune and monitor miscellaneous and general things in the operation of the Linux
@@ -15,21 +15,29 @@ before actually making adjustments. Currently, these files are in /proc/sys/fs: +- aio-max-nr +- aio-nr +- binfmt_misc/ ==> see Documentation/binfmt_misc.txt - dentry-state - dquot-max - dquot-nr +- dir-notify-enable - file-max - file-nr -- inode-max - inode-nr - inode-state +- inotify/ ==> See Documentation/filesystem/inotify.txt - overflowuid - overflowgid -- super-max -- super-nr +- suid_dumpable -Documentation for the files in /proc/sys/fs/binfmt_misc is -in Documentation/binfmt_misc.txt. +============================================================== + +aio-nr & aio-max-nr: + +aio-nr shows the current system-wide number of asynchronous io +requests. aio-max-nr allows you to change the maximum value +aio-nr can grow to. ==============================================================
@@ -71,6 +79,21 @@ ============================================================== +dir-notify-enable: + +This file controls dnotify, a directory notification mechanism, +and will not appear if dnotify support is compiled out. It was +introduced with inotify (see Documentation/filesystems/inotify.txt) +in case some people want to disable dnotify support at runtime. +There're two possible values: + +1 - dnotify is enabled (default) +0 - dnotify is disabled + +For more information about dnotify, see Documentation/dnotify.txt + +============================================================== + file-max & file-nr: The kernel allocates file handles dynamically, but as yet it
@@ -90,17 +113,11 @@ ============================================================== -inode-max, inode-nr & inode-state: +inode-nr & inode-state: As with file handles, the kernel allocates the inode structures dynamically, but can't free them yet. -The value in inode-max denotes the maximum number of inode -handlers. This value should be 3-4 times larger than the value -in file-max, since stdin, stdout and network sockets also -need an inode struct to handle them. When you regularly run -out of inodes, you need to increase this value. - The file inode-nr contains the first two items from inode-state, so we'll skip to that file...
@@ -131,20 +148,21 @@ ============================================================== -super-max & super-nr: - -These numbers control the maximum number of superblocks, and -thus the maximum number of mounted filesystems the kernel -can have. You only need to increase super-max if you need to -mount more filesystems than the current value in super-max -allows you to. - -============================================================== +suid_dumpable: -aio-nr & aio-max-nr: +This value can be used to query and set the core dump mode for setuid +or otherwise protected/tainted binaries. The modes are -aio-nr shows the current system-wide number of asynchronous io -requests. aio-max-nr allows you to change the maximum value -aio-nr can grow to. +0 - (default) - traditional behaviour. Any process which has changed + privilege levels or is execute only will not be dumped +1 - (debug) - all processes dump core when possible. The core dump is + owned by the current user and no security is applied. This is + intended for system debugging situations only. Ptrace is unchecked. +2 - (suidsafe) - any binary which normally would not be dumped is dumped + readable by root only. This allows the end user to remove + such a dump but not access it directly. For security reasons + core dumps in this mode will not overwrite one another or + other files. This mode is appropriate when adminstrators are + attempting to debug problems in a normal environment. ==============================================================
Documentation/sysctl/kernel.txt renamed from Documentation/sysctl/kernel.txt.old +50 -27
149 lines not on this page · raw message
Quoted 5 lines · Diego Calleja
In http://bugzilla.kernel.org/show_bug.cgi?id=6145 you asked to update
the sysctl docs. I've updated them and added/deleted the neccesary stuff (except the ones that I don't know what on earth are they doing because they're not...documented).
OK..
Quoted 4 lines
However it looks like there's
duplication -Documentation/filesystems/proc.txtseems to document all that aswell (but in a single doc, which makes it a bit unreadable for such big document, IMO)
Yes, the duplication is silly and wasteful and error-inducing.
Quoted 4 lines
What should be the best step? Kill
Documentation/sysctl/and keepfilesystems/proc.txtupdated and maybe split it in several files to make it more readable? Update it but maintain in sync withfilesystems/proc.txt? delete proc.txt and keep sysctl/ updated...?
I'd have thought that keeping everything in Documentation/sysctl/*.txt and killing proc.txt would be the best approach?
But I haven't looked into it much. You have - what approach are you recommending?
Quoted 5 lines · Andrew Morton
I'd have thought that keeping everything in
Documentation/sysctl/*.txtand killing proc.txt would be the best approach?But I haven't looked into it much. You have - what approach are you recommending?
Well, filesystems/proc.txt is somewhat more updated than sysctl/* - 2.4 vs 2.2 (sic) (and some small 2.6 updates spread in both places). However, filesystems/* should only contain IMO docs about the filesystem themselves not about the data in the filesystems, and proc.txt only documents sysctls, nothing else.
So I guess the Right Thing would be to move proc.txt to Documentation/sysctl, and use e-violence to make people update the non-documented parts ;) (And apparently there's more sysctl stuff lost in the noise like networking/ip-sysctl.txt, etc)
I'll try to move everything to sysctl/ and will post a RFC about it.
(Wouldn't have sense to have a Documentation/sysfs directory documenting the sysfs interfaces aswell?)
Quoted 3 lines · Diego Calleja
(Wouldn't have sense to have a
Documentation/sysfsdirectory documenting
the sysfs interfaces aswell?)
Spose so. It would take a lot of your e-violence to get that filled out.