7 Signal Chaining

Signal chaining enables you to write applications that need to install their own signal handlers. This facility is available on Solaris, 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 the libjsig.so shared library before the libc/libthread/libpthread library. This library ensures that calls such as signal(), sigset(), and sigaction() 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.

  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() , and sigaction() 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 the LD_PRELOAD environment variable available on Solaris and Linux.

• DYLD_FORCE_FLAT_NAMESPACE: Enables functions in the libjsig 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 is libjsig.dylib not libjsig.so as it is on Solaris or Linux.