JEP 245: Validate JVM Command-Line Flag Arguments

Summary

Validate the arguments to all JVM command-line flags so as to avoid crashes, and ensure that appropriate error messages are displayed when they are invalid.

Non-goals

• We will not validate arguments to flags that are not processed by the JVM.

• We will not attempt to adjust arguments to fall within allowed ranges; we will only detect incorrect arguments, not correct them.

Success Metrics

Any JVM flag that takes a value and is provided an out-of-range value is shown to not cause a JVM crash but rather issue an informative error message. This will be done for JVM flags whether they are set ergonomically (e.g., in include files), set on the command line, set via tool input, or set via APIs (e.g., attachListener/jcmd, or java.lang.management).

Description

Any interface, whether it be programmatic or user-visible, must provide adequate capability to validate input values. In the case of command lines, it is critical to implement range checks for arguments which require a user-specified value. The globals.hpp source file contains the origin of the flag value and rudimentary range checking. Expanding and completing this can provide correct coverage.

In addition, we should define a framework to make it very easy for someone adding a new JVM command-line flag to take advantage of this validity checking. The framework should be flexible, allowing for checks of a single value, being between a minimum and maximum value, or being within a set of values, etc.

We will implement this feature by expanding existing macro tables (e.g., RUNTIME_FLAGS) to add optional range(min, max) and constraint(function_pointer) entries. Current range-checking and other ad-hoc validation code will be ported over and then removed.

The range and constraints checks are done every time a flag changes, as well as late in the JVM initialization routine (i.e., in init_globals() after stubRoutines_init2()) at the time when all flags have their final values set. We will continue to check the manageable flags as long as the JVM runs.

For those flags that depend on others that might not be set at the time of setting the flag in question, we will provide a mechanism in form of an API (CommandLineFlags::finishedInitializing()) to let constraint functions know when all flags have their final values set and change their behavior from NOP to error as needed.

Intercepting flag value changes is done at a low level in CommandLineFlags::xxxxAtPut setters to guarantee that manageable flags are checked for their ranges and constraints (e.g., flags set via jcmd). For example, using jcmd PID VM.set_flag MinHeapFreeRatio 101, which is outside the allowed range, will print out

PID:
MinHeapFreeRatio error: must have value in range [0...100]

in the jcmd output.

The range checks do not impose any behavioral changes upon the JVM initialization process. In particular they do not terminate the JVM, but instead they propagate their status up to the code that uses them. The constraint functions can terminate the JVM to match existing custom behavior as needed.

The range/constraint checks are non-verbose by default, to inhibit their messages from being printed out. Range checks do print error messages on the error stream during JVM initialization, in order to match current behavior. Printing to the error stream for manageable flags is inhibited; any error status will, rather, be handled by the WriteableFlags code to provide verbose status into the provided FormatBuffer so that it can be then printed by jcmd process itself instead of by the target process.

In the event of range-check failure during JVM initialization, an error message is printed by default in the following form:

uintx UnguardOnExecutionViolation = 3 is outside the allowed range [ 0 ... 2 ]

We are not, however, committing to any particular format at this time. Existing tests that expect a certain message format will have to be modified to allow the new format.

The existing behavior is not changed with respect to clamping flags to fit within a specified range (i.e., we do not clamp), even though we have that capability. We conform to the existing behavior during error detection while initializing the JVM (i.e., we terminate the process).

Alternatives

Variadic macros offered a slightly different, and possibly a cleaner, way to define ranges and constraints, but a "trailing comma with empty args" issue in the Solaris C++ compiler prevented the adoption of this approach.