Signal handling

Signals that are used by the Eclipse 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:

The VM calls the equivalent application signal handler.
The VM calls any hooks that are installed by the application (unexpected shutdown hooks for exceptions or errors, shutdown or exit hooks for interrupts).
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 that is 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.

On all platforms except Windows, when an asynchronous signal SIGABRT, SIGQUIT, or SIGUSR2 occurs, the process ID (pid) and the name of the process that sent the signal is recorded and reported in a tracepoint. While SIGABRT creates a tracepoint, SIGQUIT and SIGUSR2 might or might not create a tracepoint. For example, SIGABRT creates a j9dmp.16 tracepoint with the following content that includes the pid and the process name:

j9dmp.16        - SIGABRT received from process id 608 name '/usr/bin/bash'

SIGQUIT, SIGUSR2 might create a tracepoint j9jcl.540 with similar content.

The sending pid information for these signals is also reported in the javacore. For example,

1TISIGPID      Signalling process id 608 name "/usr/bin/bash"

The SIGINT, SIGHUP, and SIGTERM signals create a tracepoint that includes the pid but these signals do not create javacore files.

j9vm.807       - SIGTERM received from process id 601 name '/usr/bin/bash'

On the z/OS® platform, the pid is included in the tracepoint and reported in the javacore but the process name is not included. For example,

j9dmp.16        - SIGABRT received from process id 608

Signals on Linux

Signal	Type	Description	Option to disable signal
`SIGBUS (7)`	Exc	Incorrect memory access (data misalignment)	`-Xrs` or `-Xrs:sync`
`SIGFPE (8)`	Exc	Floating point exception (divide by zero)	`-Xrs` or `-Xrs:sync`
`SIGILL (4)`	Exc	Illegal instruction (attempt to call unknown machine instruction)	`-Xrs` or `-Xrs:sync`
`SIGSEGV (11)`	Exc	Incorrect memory access (write to inaccessible area)	`-Xrs` or `-Xrs:sync`
`SIGABRT (6)`	Err	Abnormal termination, raised by the VM when a VM fault is detected	`-Xrs` or `-Xrs:sync`
`SIGHUP (1)`	Int	Hang up, VM exits normally	`-Xrs`
`SIGINT (2)`	Int	Interactive attention (CTRL-C), VM exits normally	`-Xrs`
`SIGTERM (15)`	Int	Termination request, VM exits normally	`-Xrs`
`SIGUSR2 (12)`	Int	User-defined signal for triggering a dump agent	`-Xrs`
`SIGCHLD (17)`	Con	Used by the `java.lang.Process` implementation	-
`SIGQUIT (3)`	Con	Quit signal from a terminal, which triggers a Java dump by default	`-Xrs`
`SIGRTMAX -2 (62)`	Con	Used by the `java.net` class library code	-
`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)	-
`SIGTRAP (5)`	Con	Used by the JIT	`-Xrs` or `-Xrs:sync`

Notes:

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

Signals on macOS

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

Note:

The handling of SIGABRT is configurable with the -XX:[+|-]HandleSIGABRT option.
The handling of SIGUSR2 is configurable with the -XX:[+|-]HandleSIGUSR2 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`
`SIGFPE (8)`	Exc	Floating point exception (divide by zero)	`-Xrs` or `-Xrs:sync`
`SIGILL (4)`	Exc	Illegal instruction (attempt to call unknown machine instruction))	`-Xrs` or `-Xrs:sync`
`SIGSEGV (11)`	Exc	Incorrect memory access (write to inaccessible area)	`-Xrs` or `-Xrs:sync`
`SIGABRT (3)`	Err	Abnormal termination, raised by the VM when a VM fault is detected	`-Xrs` or `-Xrs:sync`
`SIGHUP (1)`	Int	Hang up, VM exits normally	`-Xrs`
`SIGINT (2)`	Int	Interactive attention (CTRL-C), VM exits normally	`-Xrs`
`SIGTERM (15)`	Int	Termination request, VM exits normally	`-Xrs`
`SIGUSR2 (17)`	Int	User-defined signal for triggering a dump agent	`-Xrs`
`SIGCHLD (20)`	Con	Used by the `java.lang.Process` implementation	-
`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`
`SIGUSR1 (16)`	Con	Used by the `java.net` class library code	-

Note:

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

Signals on AIX

Signal	Type	Description	Option to disable signal
`SIGBUS (10)`	Exc	Incorrect memory access (data misalignment)	`-Xrs` or `-Xrs:sync`
`SIGFPE (8)`	Exc	Floating point exception (divide by zero)	`-Xrs` or `-Xrs:sync`
`SIGILL (4)`	Exc	Illegal instruction (attempt to call unknown machine instruction))	`-Xrs` or `-Xrs:sync`
`SIGSEGV (11)`	Exc	Incorrect memory access (write to inaccessible area)	`-Xrs` or `-Xrs:sync`
`SIGABRT (6)`	Err	Abnormal termination, raised by the VM when a VM fault is detected	`-Xrs` or `-Xrs:sync`
`SIGHUP (1)`	Int	Hang up, VM exits normally	`-Xrs`
`SIGINT (2)`	Int	Interactive attention (CTRL-C), VM exits normally	`-Xrs`
`SIGTERM (15)`	Int	Termination request, VM exits normally	`-Xrs`
`SIGUSR2 (31)`	Int	User-defined signal for triggering a dump agent	`-Xrs`
`No Name (40)`	Con	Used by the VM for control purposes	`-Xrs`
`SIGCHLD (20)`	Con	Used by the `java.lang.Process` implementation	-
`SIGQUIT (3)`	Con	Triggers a Java dump by default	`-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`
`SIGRTMAX -1 (56)`	Con	Used by the `java.net` class library code	-
`SIGRTMIN (50)`	Con	Used by the VM for thread introspection	-

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.
The handling of SIGUSR2 is configurable with the -XX:[+|-]HandleSIGUSR2 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 already installed by the VM. 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`

In the absence of signal chaining, the VM does not allow application signal handlers for certain signals that are used internally by the VM, including the SIGUSR2 signal. You can use the -XX:-HandleSIGUSR2 option instead, whereby the VM signal handler is not installed on VM startup. Therefore, the application signal handler, if available, takes over the handling of the SIGUSR2 signal. If there is no application signal handler, then the operating system's default signal handler is used.

For more information about this option that affects the handling of the SIGUSR2 signal, see -XX:[+|-]HandleSIGUSR2.

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>

Signal handling

Signals on Linux

Signals on macOS

Signals on Windows

Signals on z/OS

Signals on AIX

Signal chaining

See also