8 Signal Chaining
Signal chaining enables you to write applications that need to install their own signal handlers. This facility is available on Linux and macOS.
The signal chaining facility has the following features:
-
Support for preinstalled signal handlers when you create Oracle’s HotSpot Virtual Machine.
When the HotSpot VM is created, the signal handlers for signals that are used by the HotSpot VM are saved. During execution, when any of these signals are raised and are not to be targeted at the HotSpot VM, the preinstalled handlers are invoked. In other words, preinstalled signal handlers are chained behind the HotSpot VM handlers for these signals.
-
Support for the signal handlers that are installed after you create the HotSpot VM, either inside the Java Native Interface code or from another native thread.
Your application can link and load thelibjsig.so
shared library before thelibc/libthread/libpthread
library. This library ensures that calls such assignal()
,sigset()
, andsigaction()
are intercepted and don’t replace the signal handlers that are used by the HotSpot VM, if the handlers conflict with the signal handlers that are already installed by HotSpot VM. Instead, these calls save the new signal handlers. The new signal handlers are chained behind the HotSpot VM signal handlers for the signals. During execution, when any of these signals are raised and are not targeted at the HotSpot VM, the preinstalled handlers are invoked.Note:
As of Java 16 the use of thesignal
andsigset
functions are deprecated, and support for those functions will be removed in a future release. Use thesigaction
function instead.If support for signal handler installation after the creation of the VM is not required, then the
libjsig.so
shared library is not needed.To enable signal chaining, perform one of the following procedures to use the
libjsig.so
shared library:-
Link the
libjsig.so
shared library with the application that creates or embeds the HotSpot VM:cc -L libjvm.so-directory -ljsig -ljvm java_application.c
-
Use the
LD_PRELOAD
environment variable:-
Korn shell (ksh):
export LD_PRELOAD=libjvm.so-directory/libjsig.so; java_application
-
C shell (csh):
setenv LD_PRELOAD libjvm.so-directory/libjsig.so; java_application
-
The interposed
signal()
,sigset()
, andsigaction()
calls return the saved signal handlers, not the signal handlers installed by the HotSpot VM and are seen by the operating system. -
Note:
The SIGQUIT
, SIGTERM
, SIGINT
, and SIGHUP
signals cannot be chained. If the application must handle these signals, then consider using the —Xrs
option.
Enable Signal Chaining in macOS
To enable signal chaining in macOS, set the following environment variables:
-
DYLD_INSERT_LIBRARIES
: Preloads the specified libraries instead of theLD_PRELOAD
environment variable available on Linux. -
DYLD_FORCE_FLAT_NAMESPACE
: Enables functions in thelibjsig
library and replaces the OS implementations, because of macOS’s two-level namespace (a symbol's fully qualified name includes its library). To enable this feature, set this environment variable to any value.
The following command enables signal chaining by preloading the libjsig
library:
$ DYLD_FORCE_FLAT_NAMESPACE=0 DYLD_INSERT_LIBRARIES="JAVA_HOME/lib/libjsig.dylib" java MySpiffyJavaApp
Note:
The library file name on macOS islibjsig.dylib
not libjsig.so
as it is on
Linux.