Signal handling

Signals used by the OpenJ9 VM include the following types:

  • Exceptions (Exc): Raised synchronously by the operating system whenever an unrecoverable condition occurs (not applicable on Windows systems).
  • Errors (Err): Raised by the OpenJ9 VM when an unrecoverable condition occurs.
  • Interrupts (Int): Raised asynchronously from outside a VM process to request a VM exit.
  • Controls (Con): Other signals that are used by the VM for control purposes.

For exceptions and errors, if the VM cannot handle the condition and recover, dumps are produced and a controlled shut down sequence takes place. Interrupts also cause the VM to enter a controlled shut down sequence, but without generating dumps. The shutdown sequence is equivalent to calling System.exit(), which results in the following steps:

  1. The VM calls the equivalent application signal handler.
  2. The VM calls any hooks installed by the application (unexpected shutdown hooks for exceptions or errors, shutdown or exit hooks for interrupts).
  3. The VM does any final clean up.

Control signals are used for internal control purposes and do not cause the VM to end.

The VM takes control of any signals for Java threads. For non-Java threads, the VM passes control to an application handler, if one is installed. If the application does not install a signal handler, or signal chaining is turned off, the signal is either ignored or the default action is taken. Signal chaining is controlled by the -Xsigchain / -Xnosigchain command-line option.

The signals relevant to each platform are detailed in the sections that follow.

When reading each table, a number supplied after the signal name is the standard numerical value for that signal.

Note that certain signals on VM threads cause OpenJ9 to shutdown. An application signal handler should not attempt to recover from these signals unless it no longer requires the VM.

Signals on Linux

Signal Type Description Option to disable signal
SIGBUS (7) Exc Incorrect memory access (data misalignment) -Xrs or -Xrs:sync
SIGSEV (11) Exc Incorrect memory access (write to inaccessible area) -Xrs or -Xrs:sync
SIGILL (4) Exc Illegal instruction (attempt to call unknown machine instruction) -Xrs or -Xrs:sync
SIGFPE (8) Exc Floating point exception (divide by zero) -Xrs or -Xrs:sync
SIGABRT (6) Err Abnormal termination, raised by the VM when a VM fault is detected -Xrs or -Xrs:sync
SIGINT (2) Int Interactive attention (CTRL-C), VM exits normally -Xrs
SIGTERM (15) Int Termination request, VM exits normally -Xrs
SIGHUP (1) Int Hang up, VM exits normally -Xrs
SIGQUIT (3) Con Quit signal from a terminal, which triggers a Java dump by default -Xrs
SIGTRAP (5) Con Used by the JIT -Xrs or -Xrs:sync
SIGRTMIN (34) Con Used by the VM for thread introspection -
SIGRTMIN +1 (35) Con Used by the VM for Runtime Instrumentation (Linux for IBM Z systems only) -
SIGRTMAX -2 (62) Con Used by the java.net class library code -
SIGCHLD (17) Con Used by the java.lang.Process implementation -

Notes:

  • The use of SIGRTMIN is configurable with the -Xdump:suspendwith=<num> option.
  • The handling of SIGABRT is configurable with the -XX[+|-]HandleSIGABRT option.

Signals on macOS

Signal Type Description Option to disable signal
SIGBUS (10) Exc Incorrect memory access (data misalignment) -Xrs or -Xrs:sync
SIGSEV (11) Exc Incorrect memory access (write to inaccessible area) -Xrs or -Xrs:sync
SIGILL (4) Exc Illegal instruction (attempt to call unknown machine instruction)) -Xrs or -Xrs:sync
SIGFPE (8) Exc Floating point exception (divide by zero) -Xrs or -Xrs:sync
SIGABRT (6) Err Abnormal termination, raised by the VM when a VM fault is detected -Xrs or -Xrs:sync
SIGINT (2) Int Interactive attention (CTRL-C), VM exits normally -Xrs
SIGTERM (15) Int Termination request, VM exits normally -Xrs
SIGHUP (1) Int Hang up, VM exits normally -Xrs
SIGQUIT (3) Con Quit signal from a terminal, which triggers a Java dump by default -Xrs
SIGTRAP (5) Con Used by the JIT -Xrs or -Xrs:sync
SIGCHLD (20) Con Used by the java.lang.Process implementation -
SIGUSR1 (30) Con Used by the VM for thread introspection -
SIGIO (23) Con Used by the java.net class library code -

Note:

  • The handling of SIGABRT is configurable with the -XX[+|-]HandleSIGABRT option.

Signals on Windows

Signal Type Description Option to disable signal
SIGINT (2) Int Interactive attention (CTRL-C), VM exits normally -Xrs
SIGTERM (15) Int Termination request, VM exits normally -Xrs
SIGBREAK Con A break signal from a terminal. By default, this triggers a Java dump -Xrs

Notes:

The following mechanisms are used by OpenJ9 for signal handling:

  • structured exception handling (32-bit VM only)
  • AddVectoredExceptionHandler() API (64-bit JVM only)
  • SetConsoleCtrlHandler() applicable

All mechanisms can be disabled by using the -Xrs option. However, only structured exception handling and the use of the AddVectoredExceptionHandler() API can be disabled by using the -Xrs:sync option. The option -Xnosigchain, which turns off signal handler chaining, is ignored on Windows systems.

Signals on z/OS

Signal Type Description Option to disable signal
SIGBUS (10) Exc Incorrect memory access (data misalignment) -Xrs or -Xrs:sync
SIGSEV (11) Exc Incorrect memory access (write to inaccessible area) -Xrs or -Xrs:sync
SIGILL (4) Exc Illegal instruction (attempt to call unknown machine instruction)) -Xrs or -Xrs:sync
SIGFPE (8) Exc Floating point exception (divide by zero) -Xrs or -Xrs:sync
SIGABRT (3) Err Abnormal termination, raised by the VM when a VM fault is detected -Xrs or -Xrs:sync
SIGINT (2) Int Interactive attention (CTRL-C), VM exits normally -Xrs
SIGTERM (15) Int Termination request, VM exits normally -Xrs
SIGHUP (1) Int Hang up, VM exits normally -Xrs
SIGQUIT (24) Con Quit signal from a terminal, triggers a Java dump by default -Xrs
SIGTRAP (26) Con Used by the JIT -Xrs or -Xrs:sync
SIGCHLD (20) Con Used by the java.lang.Process implementation -
SIGUSR1 (16) Con Used by the java.net class library code -

Notes:

  • The handling of SIGABRT is configurable with the -XX[+|-]HandleSIGABRT option.

Signals on AIX

Signal Type Description Option to disable signal
SIGBUS (10) Exc Incorrect memory access (data misalignment) -Xrs or -Xrs:sync
SIGSEV (11) Exc Incorrect memory access (write to inaccessible area) -Xrs or -Xrs:sync
SIGILL (4) Exc Illegal instruction (attempt to call unknown machine instruction)) -Xrs or -Xrs:sync
SIGFPE (8) Exc Floating point exception (divide by zero) -Xrs or -Xrs:sync
SIGABRT (6) Err Abnormal termination, raised by the VM when a VM fault is detected -Xrs or -Xrs:sync
SIGINT (2) Int Interactive attention (CTRL-C), VM exits normally -Xrs
SIGTERM (15) Int Termination request, VM exits normally -Xrs
SIGHUP (1) Int Hang up, VM exits normally -Xrs
SIGQUIT (3) Con Triggers a Java dump by default -Xrs
No Name (40) Con Used by the VM for control purposes -Xrs
SIGRECONFIG (58) Con Reserved to detect changes to resources (CPUs, processing capacity, or physical memory) -Xrs
SIGTRAP (5) Con Used by the JIT -Xrs or -Xrs:sync
SIGRTMIN (50) Con Used by the VM for thread introspection -
SIGRTMAX -1 (56) Con Used by the java.net class library code -
SIGCHLD (20) Con Used by the java.lang.Process implementation -

Notes:

  • VM performance is affected if you install a signal handler for SIGTRAP (5) or SIGRECONFIG (58) because these signals are used for internal control purposes.
  • If you want to generate floating point exceptions, use the following call in your code to generate a SIGFPE signal: fp_trap( P_TRAP_SYNC). Although you can use the C compiler -qflttrap setting to generate SIGTRAP signals to trap floating point exceptions, this mechanism can affect the JIT compiler.
  • The handling of SIGABRT is configurable with the -XX[+|-]HandleSIGABRT option.

Signal chaining

Signal chaining allows application code to interoperate with VM signal handling. By linking and loading a shared library, certain calls can be intercepted so that the application handlers do not replace the VM signal handlers. Instead, the application handlers are chained behind the VM handlers. If signals that are raised do not target the VM, the application handlers take over. Signals that can be chained include signal(), sigset(), and sigaction().

The following table shows the shared library that must be linked with the application that creates or embeds a VM, and the command line syntax to use with the compiler, where available:

Operating system Shared library Method for linking
Linux, macOS, and z/OS libjsig.so gcc -L$JAVA_HOME/bin -ljsig -L$JAVA_HOME/lib/j9vm -ljvm <java_application>.c
Windows jsig.dll Link the DLL with the application that creates or embeds a VM
AIX libjsig.so cc_r [-q64] <other_compile/link_parameter> -L<java_install_dir> -ljsig -L<java_install_dir>/lib/j9vm -ljvm <java_application>.c

Note: On Linux, macOS, and z/OS systems, you can use the LD_PRELOAD environment variable as an alternative method to the command line for linking the shared library as shown in the following list:

  • bash and ksh shells: export LD_PRELOAD=$JAVA_HOME/lib/libjsig.so; <java_application>
  • csh shell: setenv LD_PRELOAD=$JAVA_HOME/lib/libjsig.so; <java_application>

See also