Solaris gives us a lesson in how not to write documentation
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):
rebootutility does not execute the scripts in
/etc/rcnum.dor 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,
shoots your system in the head instead of doing an orderly shutdown.
Despite the wording earlier in the manpage that 'the
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
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
the traditional System V init behavior,
reboot's behavior in Solaris 8 (as far as I know),
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
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.