> I was recently hacking on some of the scripts in > /lib/svc/method to change the way my OpenSolaris > install booted. In the process I found myself needing > to understand what all these scripts were actually > doing. This was going along well until I hit a line > that had this: > devfsadm -I > > I ran off to the man page to see what this -I option > does and surprisingly its not documented. At the time > I decided to leave off the option which lead to much > troubleshooting later on. All of that effort could > have been avoided if these options were documented > were all system administrators look for those > answers. > > I filed a bug on this because obviously -I(and -P > that i found later) are legitimate options that the > devfsadm program understands. The bug is located > here: > http://bugs.opensolaris.org/view_bug.do?bug_id=6707975 > > > In response to the bug I was told these options are > "private" options by the engineer working on the bug. > The source for this command is freely available > here: > http://src.opensolaris.org/source/xref/onnv/onnv-gate/ > usr/src/cmd/devfsadm/devfsadm.c > In the switch block at line 738 I was able to get a > good idea of what these options do based on the > comments. Obviously, they are not *that* private if > the source is easily obtained and understood. > > I bring this up here because if OpenSolaris is going > to be an open source project all aspects of it need > to behave like one and this is clearly an area that > is exhibiting a closed source mind set still.
This discussion has come up before; private (or undocumented) != closed, more on that below. > I have attached an updated version of the man page > for devfsadm to this post based on what the comments > in devfsadm.c indicated. Some things aren't documented because the end user isn't supposed to fool with them, or at any rate it may not be supported if they do; or the developers wish to reserve the right to change or remove them without notice, so that their usual diligence about preserving backwards compatibility won't paralyze future development. That is the sense in which such things are private, not that they are actually secret or anything, as you found. Having said that, I personally wouldn't mind seeing "private" options documented as long as the documentation clearly states which options are private. That for private options, environment variables, and configuration files in particular, since those will probably be referenced in scripts or other plain ASCII files, or be visible in ps output, and thus be relatively noticable. Not that under normal circumstances, anyone should be fooling with system scripts or "private" config files; usually either filing a bug/rfe or finding some way to achieve the result by adding new files that wouldn't be overwritten or broken by an upgrade would be more sensible. And of course, most people that would fool with /lib/svc/method scripts could (as you did) make the leap to looking at the C source of devfsadm to understand such details (at which point they'd probably have a better idea of their _current_ behavior and limitations than any man page could provide, but they'd be wise to keep in mind that unless they can always find (and always check) source corresponding to what they're running after every patch/upgrade/whatever, undocumented features (or features documented but described as private or volatile) could change without notice. See also http://www.opensolaris.org/os/community/arc/policies/interface-taxonomy/ In general, you shouldn't be using anything private, nor changing anything that uses something private; and if you want your work to remain unbroken over subsequent upgrades, you might want to avoid using anything other than committed interfaces. (consider that to be good discipline for writing anything portable, which would have even stricter standards as to what should and shouldn't be used) But just maybe there are times when being able to simply _understand_ something private, without necessarily having to dig into C source code, might not be a bad idea, if only to be aware that it's something that has to be done, and where it's being done, so that one can for example (as in your case?) be aware of its necessary place in the sequence of events before and after. This message posted from opensolaris.org _______________________________________________ opensolaris-discuss mailing list [email protected]
