Add documentation for the new semantics of option -Xrs
(ReduceSignalUsage=true).

See, for instance, bug # 4345157 for related details.


Documentation along the following lines:

In the non-standard options, document:

-Xrs "Reduce usage of OS signals by Java/VM"

[This also needs to be added to the java -X message).

In the section that describes the signals used by the VM:

(a) For Solaris add:

"In J2SE 1.3, the Shutdown Hooks facility was introduced to allow orderly
shutdown of a Java application. See <relevant section> for details of this
feature. The Shutdown Hooks feature uses signals SIGHUP, SIGINT and SIGTERM
to initiate shutdown sequences. When a native program that embeds the Java VM,
or a native method, uses these signals (by replacing the default handlers
for any of these signals), there is a possibility of interference with the
Shutdown Hooks feature.

"Similarly, the Java VM uses SIGQUIT to dump java thread stacks to allow
monitoring or debugging of the Java application, a feature present also
in J2SE 1.2 and earlier versions.

"To avoid such interference, and to allow the user's native code to be able
to control the handling of these signals, the `-Xrs' option may be used.
This option turns off the the Shutdown Hooks feature, allowing the
user's native code to install handlers for these signals without any
interference with the virtual machine.

"As an obvious side-effect, when the `-Xrs' option is used, neither the
Shutdown Hooks feature nor the SIGQUIT thread dumping feature are available."

(b) For Linux and Win32, appropriate modifications should be made to the
above text to rename the signals to the ones used on these platforms.

----------------------------------------------------------------------
Revised suggested text:
----
Signal Usage by the Sun Java virtual machine, Shutdown Hooks, and
Thread Dumping:

In J2SE 1.3, the Shutdown Hooks facility was added to allow orderly
shutdown of a Java application. The intent was to allow user cleanup
code (such as closing database connections) to run at shutdown, even
if the JVM terminates abruptly.

On Unix platforms, Sun's JVM catches signals to implement shutdown
hooks for abnormal VM termination; on Windows platforms, the JVM
watches for console control events. Specifically, on Solaris and
Linux, the JVM uses SIGHUP, SIGINT, and SIGTERM to initiate the
running of shutdown hooks. On Windows, the VM registers a console
control handler which begins shutdown hook processing and returns TRUE
for CTRL_C_EVENT, CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and
CTRL_SHUTDOWN_EVENT.

The JVM uses a similar mechanism to implement the pre-1.2 feature of
dumping thread stacks for debugging purposes. On Solaris and Linux,
Sun's JVM uses SIGQUIT to perform thread dumps; on Windows,
CTRL_BREAK_EVENT.

On Unix platforms, applications embedding the VM frequently need to
trap signals like SIGINT or SIGTERM. On Windows, if the JVM is run as
a service (for example, the servlet engine for a web server), it can
receive CTRL_LOGOFF_EVENT but should not initiate shutdown since the
operating system will not actually terminate the process.

To address these problems the -Xrs command line option has been added
in 1.3.1. Specifying -Xrs to Sun's JVM has the following effects:

1. On Solaris and Linux, the signal masks for SIGINT, SIGTERM, SIGHUP,
   and SIGQUIT are not changed by the JVM, and signal handlers for
   these signals are not installed.

2. On Windows, the JVM does not install a console control handler,
   implying that it does not watch for or process CTRL_C_EVENT,
   CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.

The consequences of specifying -Xrs are twofold:

1. SIGQUIT/Ctrl-Break thread dumps are not available.

2. User code is responsible for causing shutdown hooks to run, for
   example by calling System.exit() when the JVM is to be terminated.


kenneth.russell@eng 2000-11-22