Solaris gives us a lesson in how not to write documentation

March 9, 2014

Here are links to the manpages for reboot in Solaris 8, Solaris 9, and Solaris 10 (or the more readable Illumos version, which is probably closer to the Solaris 11 version). They are all, well, manual-pagey, and thus most system administrators have well honed skills in how to read them. If you read any of these, it probably looks basically harmless. If you read them in succession you'll probably wind up feeling that they're all basically the same, although Solaris 10 has grown some new x86-related stuff.

This is an illusion and a terrible mistake, because at the very bottom of the Solaris 9, Solaris 10, and Illumos versions you will find the following new section (presented in its entirety):

NOTES

The reboot utility does not execute the scripts in /etc/rcnum.d or execute shutdown actions in inittab(4). To ensure a complete shutdown of system services, use shutdown(1M) or init(1M) to reboot a Solaris system.

Let me translate this for you: since Solaris 9, reboot shoots your system in the head instead of doing an orderly shutdown. Despite the wording earlier in the manpage that 'the reboot utility performs a sync(1M) operation on the disks, and then a multi-user reboot is initiated. See init(1M) for details', SMF (or the System V init system in Solaris 9) is not involved in things at all (and thus no multi-user reboot happens). Reboot instead simply SIGTERMs all processes. That stuff I quoted from the DESCRIPTION section is now a flat out lie.

This is a drastic change in reboot's behavior. It is at odds with reboot's behavior in Solaris 8 (as far as I know), the traditional System V init behavior, and reboot's behavior on other systems (including but not limited to Linux). Sun decided to bury this drastic behavior change in a casual little note at the bottom of the manpage, so far down that almost no one reads that far (partly because it is after all of the really boring boilerplate).

This is truly an epic example of how not to write documentation. Vital changes go at the start of your manpages, not the very end, and they and their effects should be very clearly described instead of hidden behind what is basically obfuscation.

(The right way to do it would have been a complete rewrite of the DESCRIPTION section and perhaps an update to the SYNOPSIS as well.)

By the way, this phrasing for the NOTES section is especially dangerous in Solaris 10 and onwards where SMF services normally handle shutdown actions, not /etc/rcnum.d scripts (or inittab actions). In anything using SMF it's possible to read this section but still not realize what reboot really does because it doesn't explicitly say that SMF is bypassed too.

Update: As pointed out in comments by Ade, this appears to be historical Solaris behavior (contrary to what I thought). However, it is not the (documented) behavior of other System V R4 systems such as SGI Irix and it is very likely to surprise people coming from other Unixes.


Comments on this page:

I don't believe this behaviour has ever been different in Solaris. Here's the manual for Solaris 7.

Certainly, it's always been clear to me that 'reboot' is the quick and (slightly) dirty way to restart a Solaris system, especially if there's nothing like a database that must be shut down cleanly, whereas 'init 6' runs all the rc6 scripts. The 'reboot' command was carried over from SunOS 4. I will agree that the man page doesn't labour the point much, which is presumably why the behaviour was clarified in the Solaris 9 version.

Agreed. I created a bug in Illumos about this: https://www.illumos.org/issues/4676

Sadly, I'm plenty busy with other bugs to fix this (low-priority) one.

Regardless, thanks for blogging about it and in the process drawing my attention to it. This needs to be fixed.

By cks at 2014-03-10 10:31:48:

One of the problems with the reboot versus init behavior split is that there are some things you can only do via reboot. This makes life rather awkward if you are, for example, remotely administering a server (including from your office to the machine room). It also makes it tempting to use reboot directly for these things (especially when the fine documentation talks about using eg 'reboot -- -r' without a side note that you'd better bring the system to single user mode on the console first).

Not that I'm grumpy or anything. Okay, I totally am grumpy about this.

reboot has always been this way in Solaris. My Linux'y friends often gripe about this. But it is what it is. Why not accept it, make a mental note and move ahead? :)

The BSDs (Free, Net, Open) also have the general whack-the-system behaviour:

The halt and reboot utilities flush the file system cache to disk, send all running processes a SIGTERM (and subsequently a SIGKILL) and, respectively, halt or restart the system. The action is logged, including entering a shutdown record into the user accounting database. […]

Normally, the shutdown(8) utility is used when the system needs to be halted or restarted, giving users advance warning of their impending doom and cleanly terminating specific programs.

http://www.freebsd.org/cgi/man.cgi?query=reboot

I think Sun simply carried forward the SunOS way of doing things, which emulated BSD.

Given that there's no POSIX standard for reboot(8), there is/was no consensus on what should be done.

Also of note from the "History" section of the BSD man pages:

A reboot utility appeared in Version 6 AT&T UNIX.

Written on 09 March 2014.
« Why we don't change Unix login names for people
The problem of conditional GET and caches for dynamic websites »

Page tools: View Source, View Normal, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Sun Mar 9 22:19:47 2014
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.