JEP 245: Validate JVM Command-Line Flag Arguments
|Status||Closed / Delivered|
|Component||hotspot / runtime|
|Discussion||hotspot dash dev at openjdk dot java dot net|
|Reviewed by||Christian Thalinger, Karen Kinnear, Mikael Vidstedt|
|Endorsed by||Mikael Vidstedt|
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.
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.
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.,
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
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]
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).
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.